blume 0.7.0 → 1.0.0

package/src/components/layout/RootLayout.astro

@@ -9,7 +9,13 @@ import type {
 } from "../../core/types.ts";
 import "blume:theme";
 import type { ComponentOverride } from "../../core/define-components.ts";
-import { buildStructuredData } from "../../seo/jsonld.ts";
+import {
+  OG_IMAGE_HEIGHT,
+  OG_IMAGE_TYPE,
+  OG_IMAGE_WIDTH,
+} from "../../og/dimensions.ts";
+import { buildStructuredData, toIso } from "../../seo/jsonld.ts";
+import { normalizeXHandle } from "../../seo/x-handle.ts";
 import { withBase } from "../islands/base-path.ts";
 import Analytics from "./Analytics.astro";
 import Banner from "./Banner.astro";
@@ -79,6 +85,19 @@ interface Props {
   searchEnabled: boolean;
   indexable: boolean;
   ogImage?: string | null;
+  /**
+   * Whether `ogImage` is Blume's generated card (rather than a user `seo.image`).
+   * Only the generated card has known dimensions and format, so `og:image:width`
+   * / `og:image:height` / `og:image:type` are declared for it alone — asserting
+   * 1200x630 PNG over someone's arbitrary JPEG would be a lie crawlers act on.
+   */
+  ogGenerated?: boolean;
+  /**
+   * X (Twitter) attribution: `handle` is the site's account (`twitter:site`),
+   * `creator` the author's (`twitter:creator`). The rest of the X card is read
+   * from `og:*`, so these are the only values X can't infer.
+   */
+  x?: { creator?: string; handle?: string };
   canonical?: string | null;
   editUrl?: string | null;
   askEnabled?: boolean;
@@ -154,6 +173,8 @@ const {
   searchEnabled,
   indexable,
   ogImage,
+  ogGenerated = false,
+  x,
   canonical,
   editUrl,
   askEnabled,
@@ -206,6 +227,12 @@ const PageFooterSlot = resolveSlot(layout.PageFooter, Empty);
 const FeedbackSlot = resolveSlot(layout.Feedback, PageFeedback);
 
 const strings = ui ?? EN_UI;
+// Merge the groups this layout reads directly over the English defaults so a
+// key missing from a translation (or from a not-yet-regenerated snapshot)
+// still renders instead of coming out blank — the PageActions pattern.
+const navStrings = { ...EN_UI.nav, ...strings.nav };
+const actionStrings = { ...EN_UI.actions, ...strings.actions };
+const contentStrings = { ...EN_UI.content, ...strings.content };
 // Filter search to the active language only when the site is multi-locale.
 const searchLocale =
   localeSwitch && localeSwitch.length > 1 ? locale : undefined;
@@ -238,6 +265,24 @@ if (isBare) {
 }
 const pageTitle = page.title ? `${page.title} - ${site.title}` : site.title;
 const description = page.description ?? site.description;
+// Blog posts and changelog entries are dated writing, so they take `og:type:
+// article` — the same split JSON-LD makes when it picks an article @type. Docs
+// pages (and the changelog index, which has no `type`) stay `website`.
+const ogType =
+  pageType === "blog" || pageType === "changelog" ? "article" : "website";
+// `article:*` timestamps only belong on an article; a docs page carrying them
+// would be declaring properties its `og:type` doesn't define.
+const articlePublished = ogType === "article" ? toIso(published) : undefined;
+const articleModified = ogType === "article" ? toIso(lastModified) : undefined;
+// X sizes the card from `twitter:card`: a large image needs the wide variant,
+// and a page with no image still gets a card (the compact `summary`) rather
+// than rendering as a bare link.
+const twitterCard = ogImage ? "summary_large_image" : "summary";
+// Normalized here, not just in the config schema: a page's `seo.x.creator`
+// arrives as raw frontmatter (the collections carry no schema), so the schema's
+// transform never touches it — `creator: guestauthor` still needs its `@`.
+const xSite = normalizeXHandle(x?.handle);
+const xCreator = normalizeXHandle(x?.creator);
 
 // "Last updated on <date>" — formatted in UTC to match the changelog timeline.
 const lastModifiedDate = lastModified ? new Date(lastModified) : null;
@@ -307,17 +352,46 @@ const bannerScript = banner?.dismissible
     {xDefault && <link href={xDefault} hreflang="x-default" rel="alternate" />}
     {noindex && <meta name="robots" content="noindex" />}
     {description && <meta name="description" content={description} />}
+    <meta property="og:type" content={ogType} />
+    <meta property="og:site_name" content={site.title} />
     <meta property="og:title" content={pageTitle} />
     {description && <meta property="og:description" content={description} />}
+    {canonical && <meta property="og:url" content={canonical} />}
+    {
+      articlePublished && (
+        <meta property="article:published_time" content={articlePublished} />
+      )
+    }
+    {
+      articleModified && (
+        <meta property="article:modified_time" content={articleModified} />
+      )
+    }
     {
       ogImage && (
         <>
           <meta property="og:image" content={ogImage} />
+          {ogGenerated && (
+            <>
+              <meta property="og:image:type" content={OG_IMAGE_TYPE} />
+              <meta property="og:image:width" content={String(OG_IMAGE_WIDTH)} />
+              <meta
+                property="og:image:height"
+                content={String(OG_IMAGE_HEIGHT)}
+              />
+              <meta property="og:image:alt" content={pageTitle} />
+            </>
+          )}
           <meta name="twitter:image" content={ogImage} />
-          <meta name="twitter:card" content="summary_large_image" />
+          {ogGenerated && <meta name="twitter:image:alt" content={pageTitle} />}
         </>
       )
     }
+    <meta name="twitter:card" content={twitterCard} />
+    <meta name="twitter:title" content={pageTitle} />
+    {description && <meta name="twitter:description" content={description} />}
+    {xSite && <meta name="twitter:site" content={xSite} />}
+    {xCreator && <meta name="twitter:creator" content={xCreator} />}
     {
       feeds?.map((feed) => (
         <link
@@ -345,12 +419,14 @@ const bannerScript = banner?.dismissible
     class="bg-background font-sans text-foreground antialiased"
     data-blume-code-wrap={codeWrap ? "" : undefined}
     data-blume-image-zoom={imageZoom ? "" : undefined}
+    data-i18n-copy-code={actionStrings.copyCode}
+    data-i18n-diagram-error={contentStrings.diagramError}
   >
     <a
       class="absolute start-[-999px] top-0 z-[100] bg-accent px-4 py-2 text-accent-foreground focus:start-0"
       href="#blume-content">{strings.page.skipToContent}</a
     >
-    <Banner banner={banner} />
+    <Banner banner={banner} strings={strings.banner} />
     <HeaderSlot
       askEnabled={askEnabled}
       layout={layout}
@@ -360,6 +436,7 @@ const bannerScript = banner?.dismissible
       route={page.route}
       searchEnabled={searchEnabled}
       searchLocale={searchLocale}
+      navStrings={navStrings}
       searchStrings={strings.search}
       site={site}
       switcherStrings={strings.languageSwitcher}
@@ -371,7 +448,8 @@ const bannerScript = banner?.dismissible
       data-blume-doc-grid
     >
       <aside
-        aria-label="Primary"
+        aria-label={navStrings.primary}
+        data-blume-nav-drawer
         class:list={[
           "fixed top-[var(--blume-drawer-top,4rem)] start-0 z-[35] h-[calc(100dvh-var(--blume-drawer-top,4rem))] w-64 max-w-[80vw] -translate-x-[105%] overflow-y-auto border-border border-e bg-background px-5 pt-4 pb-6 transition-transform rtl:translate-x-[105%] [:where([data-blume-nav-open])_&]:translate-x-0! lg:sticky lg:top-16 lg:z-auto lg:h-[calc(100dvh-4rem)] lg:w-auto lg:max-w-none lg:translate-x-0! lg:border-e-0 lg:bg-transparent lg:px-4",
           // A "bare" landing (the changelog index) has no sidebar column on
@@ -385,7 +463,10 @@ const bannerScript = banner?.dismissible
           // all breakpoints, outside the tab-scoped sidebar so they never change
           // with the active tab. External hrefs open in a new tab.
           navigation.featured.length > 0 && (
-            <nav aria-label="Featured" class="mb-4 border-border border-b pb-4">
+            <nav
+              aria-label={navStrings.featured}
+              class="mb-4 border-border border-b pb-4"
+            >
               <ul class="m-0 list-none p-0">
                 {navigation.featured.map((link) => {
                   const external = /^https?:\/\//u.test(link.href);
@@ -431,7 +512,7 @@ const bannerScript = banner?.dismissible
           // from opening blank.
           navigation.tabs.length > 0 && (
             <nav
-              aria-label="Sections"
+              aria-label={navStrings.sections}
               class:list={[
                 "mb-4 border-border border-b pb-4",
                 sidebar.length > 0 && "md:hidden",
@@ -463,20 +544,36 @@ const bannerScript = banner?.dismissible
             MobileNavSlot ? (
               <>
                 <div class="lg:hidden">
-                  <MobileNavSlot currentRoute={page.route} items={sidebar} />
+                  <MobileNavSlot
+                    currentRoute={page.route}
+                    items={sidebar}
+                    strings={navStrings}
+                  />
                 </div>
                 <div class="hidden lg:block">
-                  <SidebarSlot currentRoute={page.route} items={sidebar} />
+                  <SidebarSlot
+                    currentRoute={page.route}
+                    items={sidebar}
+                    strings={navStrings}
+                  />
                 </div>
               </>
             ) : (
-              <SidebarSlot currentRoute={page.route} items={sidebar} />
+              <SidebarSlot
+                currentRoute={page.route}
+                items={sidebar}
+                strings={navStrings}
+              />
             )
           }
         </nav>
       </aside>
       <main class="px-6 pt-6 pb-10 lg:px-8 xl:px-10" id="blume-content">
-        <BreadcrumbsSlot crumbs={crumbs} wide={isApiOperation} />
+        <BreadcrumbsSlot
+          crumbs={crumbs}
+          strings={navStrings}
+          wide={isApiOperation}
+        />
         <TableOfContentsSlot
           headings={tocHeadings}
           title={strings.toc.title}
@@ -542,7 +639,7 @@ const bannerScript = banner?.dismissible
       )
     }
     <button
-      aria-label="Close navigation"
+      aria-label={navStrings.closeNavigation}
       class="fixed inset-0 z-[30] hidden cursor-pointer border-0 bg-black/40 [:where([data-blume-nav-open])_&]:block lg:hidden"
       data-blume-nav-toggle
       type="button"
@@ -559,12 +656,45 @@ const bannerScript = banner?.dismissible
       // Tree-shaken out of production builds.
       import "./hydration-hint.ts";
 
+      // The closed mobile drawer is only translated off-canvas, so its links
+      // would stay in the tab order on every page. Mirror the header's
+      // `data-blume-nav-open` toggle into `inert`/`aria-hidden` — but only
+      // below `lg` (64rem), where the same element isn't the static sidebar.
+      const drawer = document.querySelector<HTMLElement>(
+        "[data-blume-nav-drawer]"
+      );
+      if (drawer) {
+        const desktop = window.matchMedia("(min-width: 64rem)");
+        const syncDrawer = () => {
+          const hidden =
+            !desktop.matches &&
+            !document.documentElement.hasAttribute("data-blume-nav-open");
+          drawer.inert = hidden;
+          if (hidden) {
+            drawer.setAttribute("aria-hidden", "true");
+          } else {
+            drawer.removeAttribute("aria-hidden");
+          }
+        };
+        syncDrawer();
+        desktop.addEventListener("change", syncDrawer);
+        new MutationObserver(syncDrawer).observe(document.documentElement, {
+          attributeFilter: ["data-blume-nav-open"],
+        });
+      }
+
       const svg = (name: string) =>
         `<svg xmlns="http://www.w3.org/2000/svg" width="15" height="15" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">${icons[name]}</svg>`;
 
       const buttonClass =
         "absolute right-3 inline-flex size-7 items-center justify-center rounded-full bg-transparent text-muted-foreground opacity-70 transition hover:bg-muted hover:text-foreground hover:opacity-100 focus-visible:opacity-100";
 
+      // Localized copy-button label, stamped on <body> by the layout markup
+      // (the Search.astro data-attribute channel) since this bundled script
+      // can't interpolate server values directly.
+      const copyCodeLabel =
+        document.body.getAttribute("data-i18n-copy-code") || "Copy code";
+
       const languageLabels: Record<string, string> = {
         astro: "Astro",
         bash: "Bash",
@@ -612,7 +742,7 @@ const bannerScript = banner?.dismissible
           : "top-2";
         button.className = `${buttonClass} ${topClass}`;
         button.setAttribute("data-blume-copy", "");
-        button.setAttribute("aria-label", "Copy code");
+        button.setAttribute("aria-label", copyCodeLabel);
         button.innerHTML = svg("copy");
         button.addEventListener("click", async () => {
           const code = pre.querySelector("code");

package/src/components/layout/Search.astro

@@ -33,8 +33,14 @@ const kbd = "rounded border border-border bg-muted px-1 py-0.5 font-mono";
 <blume-search
   class="contents"
   data-ask={askEnabled ? "" : undefined}
+  data-i18n-all={s.all}
+  data-i18n-ask={s.askAi}
+  data-i18n-ask-hint={s.askAiHint}
   data-i18n-dev={s.devOnly}
   data-i18n-empty={s.noResults}
+  data-i18n-error={s.error}
+  data-i18n-popular={s.popular}
+  data-i18n-results={s.results}
   data-locale={locale || undefined}
 >
   <button
@@ -62,7 +68,7 @@ const kbd = "rounded border border-border bg-muted px-1 py-0.5 font-mono";
       <input
         aria-label={s.label}
         autocomplete="off"
-        class="flex-1 border-0 bg-transparent text-foreground text-sm focus:outline-none [&::-webkit-search-cancel-button]:appearance-none"
+        class="flex-1 border-0 bg-transparent text-foreground text-sm pointer-coarse:text-base focus:outline-none [&::-webkit-search-cancel-button]:appearance-none"
         data-blume-search-input
         placeholder={s.placeholder}
         type="search"
@@ -119,15 +125,17 @@ const kbd = "rounded border border-border bg-muted px-1 py-0.5 font-mono";
         <span class="flex items-center gap-1">
           <kbd class={`${kbd} text-[0.65rem]`}>↑</kbd>
           <kbd class={`${kbd} text-[0.65rem]`}>↓</kbd>
-          navigate
+          {s.navigate}
         </span>
         <span class="flex items-center gap-1">
           <kbd class={`${kbd} text-[0.65rem]`}>↵</kbd>
-          open
+          {s.open}
         </span>
         <span class="flex items-center gap-1 max-md:hidden">
-          <kbd class={`${kbd} text-[0.65rem]`}>⌘J</kbd>
-          preview
+          <kbd class={`${kbd} text-[0.65rem]`} data-blume-search-preview-kbd
+            >⌘J</kbd
+          >
+          {s.preview}
         </span>
       </div>
     </div>
@@ -189,6 +197,9 @@ const kbd = "rounded border border-border bg-muted px-1 py-0.5 font-mono";
       preview!: HTMLElement;
       searchFn: SearchFn | null = null;
       loaded = false;
+      loadFailed = false;
+      /** First-open client/index load still in flight. */
+      loading = false;
       askEnabled = false;
       popular: PopularPage[] = [];
       selectables: Selectable[] = [];
@@ -198,6 +209,12 @@ const kbd = "rounded border border-border bg-muted px-1 py-0.5 font-mono";
       previewOn = true;
       devOnlyMsg = "Search is available in the production build.";
       noResultsMsg = "No results found.";
+      errorMsg = "Something went wrong. Please try again.";
+      askMsg = "Ask AI";
+      askHintMsg = "Get an instant answer from AI";
+      allMsg = "All";
+      popularMsg = "Popular";
+      resultsMsg = "Results";
       // The active locale to filter to (null when i18n is off), and whether the
       // reader has opted to search across every language instead.
       locale: string | null = null;
@@ -208,6 +225,15 @@ const kbd = "rounded border border-border bg-muted px-1 py-0.5 font-mono";
           this.getAttribute("data-i18n-dev") || this.devOnlyMsg;
         this.noResultsMsg =
           this.getAttribute("data-i18n-empty") || this.noResultsMsg;
+        this.errorMsg = this.getAttribute("data-i18n-error") || this.errorMsg;
+        this.askMsg = this.getAttribute("data-i18n-ask") || this.askMsg;
+        this.askHintMsg =
+          this.getAttribute("data-i18n-ask-hint") || this.askHintMsg;
+        this.allMsg = this.getAttribute("data-i18n-all") || this.allMsg;
+        this.popularMsg =
+          this.getAttribute("data-i18n-popular") || this.popularMsg;
+        this.resultsMsg =
+          this.getAttribute("data-i18n-results") || this.resultsMsg;
         this.locale = this.getAttribute("data-locale");
         this.dialog = this.querySelector("[data-blume-search-dialog]")!;
         this.input = this.querySelector("[data-blume-search-input]")!;
@@ -250,12 +276,18 @@ const kbd = "rounded border border-border bg-muted px-1 py-0.5 font-mono";
           });
         }
 
-        // The handler accepts ⌘K and Ctrl+K; show the right one per platform.
+        // The handlers accept both ⌘ and Ctrl chords; show the right modifier
+        // per platform on the button hint and the footer's preview hint.
+        const isApple = /mac|iphone|ipad|ipod/iu.test(navigator.platform);
         const hint = this.querySelector("[data-blume-search-kbd]");
         if (hint) {
-          hint.textContent = /mac|iphone|ipad|ipod/iu.test(navigator.platform)
-            ? "⌘K"
-            : "Ctrl K";
+          hint.textContent = isApple ? "⌘K" : "Ctrl K";
+        }
+        const previewHint = this.querySelector(
+          "[data-blume-search-preview-kbd]"
+        );
+        if (previewHint) {
+          previewHint.textContent = isApple ? "⌘J" : "Ctrl J";
         }
 
         this.querySelector("[data-blume-search-open]")?.addEventListener(
@@ -264,12 +296,22 @@ const kbd = "rounded border border-border bg-muted px-1 py-0.5 font-mono";
         );
 
         document.addEventListener("keydown", (event) => {
-          const inField = this.isField(event.target);
           if (
-            ((event.key === "k" || event.key === "K") &&
-              (event.metaKey || event.ctrlKey)) ||
-            (event.key === "/" && !inField)
+            (event.key === "k" || event.key === "K") &&
+            (event.metaKey || event.ctrlKey)
           ) {
+            // ⌘K toggles, mirroring the Ask AI panel's ⌘I: pressing it with
+            // the dialog open must close it, not re-showModal an open dialog
+            // (an InvalidStateError on older engines).
+            event.preventDefault();
+            if (this.dialog.open) {
+              this.dialog.close();
+            } else {
+              this.open();
+            }
+          } else if (event.key === "/" && !this.isField(event.target)) {
+            // "/" stays open-only; the field guard keeps it inert while
+            // typing (including in the search input itself).
             event.preventDefault();
             this.open();
           }
@@ -297,10 +339,16 @@ const kbd = "rounded border border-border bg-muted px-1 py-0.5 font-mono";
       }
 
       async open() {
+        // Re-entrant opens (e.g. the open button while already shown) must
+        // not call showModal on an open dialog.
+        if (this.dialog.open) {
+          return;
+        }
         this.dialog.showModal();
         this.input.focus();
         this.input.select();
         if (!this.loaded) {
+          this.loading = true;
           try {
             const { createSearch } = await import("blume:search-client");
             this.searchFn = await createSearch();
@@ -308,8 +356,15 @@ const kbd = "rounded border border-border bg-muted px-1 py-0.5 font-mono";
             // fetching the index) must retry on the next open, not disable
             // search until a full page reload.
             this.loaded = true;
+            this.loadFailed = false;
           } catch {
             this.searchFn = null;
+            // In dev a client can be missing by design (Pagefind's bundle
+            // only exists in the production build) — that's the "dev only"
+            // hint. The same failure in production is a real error.
+            this.loadFailed = !import.meta.env.DEV;
+          } finally {
+            this.loading = false;
           }
         }
         this.render();
@@ -322,7 +377,9 @@ const kbd = "rounded border border-border bg-muted px-1 py-0.5 font-mono";
         } else if (event.key === "ArrowUp") {
           event.preventDefault();
           this.move(-1);
-        } else if (event.key === "Enter") {
+        } else if (event.key === "Enter" && !event.isComposing) {
+          // `isComposing` guards IME input: Enter confirming a CJK conversion
+          // must commit the text, not activate the selected result.
           const item = this.selectables[this.selectedIndex];
           if (item) {
             event.preventDefault();
@@ -361,16 +418,36 @@ const kbd = "rounded border border-border bg-muted px-1 py-0.5 font-mono";
         if (!this.searchFn) {
           this.renderFilters([]);
           this.clearPreview();
-          this.setMessage(this.devOnlyMsg);
+          if (this.loading) {
+            // Typing while the first-open load (client import + index fetch)
+            // is still in flight: the dev-only hint would be wrong in
+            // production and the error message premature. Show a neutral
+            // placeholder; `open()` re-renders once the load settles.
+            this.setMessage("…");
+          } else {
+            this.setMessage(this.loadFailed ? this.errorMsg : this.devOnlyMsg);
+          }
           return;
         }
 
         const localeFilter =
           this.locale && !this.allLocales ? this.locale : undefined;
-        const result = await this.searchFn(query, {
-          locale: localeFilter,
-          section: this.activeSection ?? undefined,
-        });
+        let result: Awaited<ReturnType<SearchFn>>;
+        try {
+          result = await this.searchFn(query, {
+            locale: localeFilter,
+            section: this.activeSection ?? undefined,
+          });
+        } catch {
+          // A hosted provider can reject (network error, outage); the results
+          // list is already cleared, so show a message instead of a blank pane.
+          if (generation === this.renderGeneration) {
+            this.renderFilters([]);
+            this.clearPreview();
+            this.setMessage(this.errorMsg);
+          }
+          return;
+        }
         // Any newer render — a keystroke, a section pill, a locale toggle —
         // supersedes this one mid-await, even for the same query text;
         // appending the stale hits would duplicate rows and desync selection.
@@ -378,17 +455,30 @@ const kbd = "rounded border border-border bg-muted px-1 py-0.5 font-mono";
           return;
         }
 
+        // A section picked for an earlier query can be missing from the new
+        // pool — and when the pool has fewer than two sections the pills that
+        // would clear it are hidden too, so the stale filter would silently
+        // empty the results. Drop it and search again unfiltered.
+        if (
+          this.activeSection &&
+          !result.sections.some((s) => s.label === this.activeSection)
+        ) {
+          this.activeSection = null;
+          this.render();
+          return;
+        }
+
         this.renderFilters(result.sections);
 
         if (this.askEnabled) {
-          const group = this.addGroup("Ask AI");
+          const group = this.addGroup(this.askMsg);
           const ask = this.createAskRow(query);
           group.appendChild(ask.el);
           this.selectables.push(ask);
         }
 
         if (result.hits.length > 0) {
-          const group = this.addGroup("Results");
+          const group = this.addGroup(this.resultsMsg);
           for (const hit of result.hits) {
             const item = this.createHitRow(hit, query);
             group.appendChild(item.el);
@@ -403,13 +493,13 @@ const kbd = "rounded border border-border bg-muted px-1 py-0.5 font-mono";
 
       renderEmpty() {
         if (this.askEnabled) {
-          const group = this.addGroup("Ask AI");
+          const group = this.addGroup(this.askMsg);
           const ask = this.createAskRow("");
           group.appendChild(ask.el);
           this.selectables.push(ask);
         }
         if (this.popular.length > 0) {
-          const group = this.addGroup("Popular");
+          const group = this.addGroup(this.popularMsg);
           for (const page of this.popular) {
             const item = this.createLinkRow(page.route, page.label);
             group.appendChild(item.el);
@@ -427,7 +517,7 @@ const kbd = "rounded border border-border bg-muted px-1 py-0.5 font-mono";
         this.filters.hidden = false;
         this.filters.replaceChildren();
         const total = sections.reduce((sum, s) => sum + s.count, 0);
-        this.filters.appendChild(this.createPill("All", total, null));
+        this.filters.appendChild(this.createPill(this.allMsg, total, null));
         for (const section of sections) {
           this.filters.appendChild(
             this.createPill(section.label, section.count, section.label)
@@ -464,13 +554,13 @@ const kbd = "rounded border border-border bg-muted px-1 py-0.5 font-mono";
         el.type = "button";
         el.className = `${ROW_CLASS} ${MARK}`;
         const title = query
-          ? `Ask AI: <span class="text-muted-foreground">“${escapeHtml(query)}”</span>`
-          : "Ask AI";
+          ? `${escapeHtml(this.askMsg)}: <span class="text-muted-foreground">“${escapeHtml(query)}”</span>`
+          : escapeHtml(this.askMsg);
         el.innerHTML = `
           <span class="mt-0.5 shrink-0 text-accent">${svg("sparkles")}</span>
           <span class="flex-1">
             <span class="block truncate font-normal text-foreground text-sm">${title}</span>
-            <span class="block truncate text-muted-foreground text-sm">Get an instant answer from AI</span>
+            <span class="block truncate text-muted-foreground text-sm">${escapeHtml(this.askHintMsg)}</span>
           </span>`;
         const item: Selectable = { el, kind: "ask" };
         this.bindRow(item);

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

@@ -20,10 +20,19 @@ export const createSearch = (opts: {
   searchApiKey: string;
 }): SearchFn => {
   const client = liteClient(opts.appId, opts.searchApiKey);
-  return async (query) => {
+  return async (query, options) => {
     const { results } = await client.search<AlgoliaRecord>({
       requests: [
-        { hitsPerPage: SEARCH_LIMIT, indexName: opts.indexName, query },
+        {
+          hitsPerPage: SEARCH_LIMIT,
+          indexName: opts.indexName,
+          query,
+          // The sync uploads `locale` on every record so an i18n site can
+          // scope hosted results to the active language.
+          ...(options?.locale && {
+            facetFilters: [`locale:${options.locale}`],
+          }),
+        },
       ],
     });
     const [first] = results;

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

@@ -1,10 +1,11 @@
-import { SEARCH_LIMIT } from "./types.ts";
+import { highlight, SEARCH_LIMIT } from "./types.ts";
 import type { SearchFn, SearchHit } from "./types.ts";
 
 /**
  * Server-proxied search (Mixedbread): POST the query to a generated endpoint
- * that holds the secret key and talks to the service, then renders the
- * already-shaped hits it returns.
+ * 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.
  */
 export const createSearch =
   (opts: { api: string }): SearchFn =>
@@ -17,6 +18,11 @@ export const createSearch =
     if (!response.ok) {
       return { hits: [], sections: [] };
     }
-    const hits = (await response.json()) as SearchHit[];
-    return { hits: hits.slice(0, SEARCH_LIMIT), sections: [] };
+    const records = (await response.json()) as SearchHit[];
+    const hits = records.slice(0, SEARCH_LIMIT).map((hit) => ({
+      ...hit,
+      excerpt: highlight(hit.excerpt, query),
+      title: highlight(hit.title, query),
+    }));
+    return { hits, sections: [] };
   };

package/src/components/layout/search/orama-cloud.ts

@@ -22,8 +22,14 @@ export const createSearch = (opts: {
     api_key: opts.apiKey,
     endpoint: opts.endpoint,
   });
-  return async (query) => {
-    const results = await client.search({ limit: SEARCH_LIMIT, term: query });
+  return async (query, options) => {
+    const results = await client.search({
+      limit: SEARCH_LIMIT,
+      term: query,
+      // The sync carries `locale` on every record so an i18n site can scope
+      // hosted results to the active language.
+      ...(options?.locale && { where: { locale: options.locale } }),
+    });
     const hits = (results?.hits ?? []).map((hit) => {
       const doc = hit.document as unknown as OramaCloudRecord;
       return {

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

@@ -134,7 +134,11 @@ export const excerptFor = (
   if (query && matchIndex(content, query) >= 0) {
     return matchSnippet(content, query, 160);
   }
-  return description || `${content.slice(0, 140)}…`;
+  if (description) {
+    return description;
+  }
+  const head = content.slice(0, 140);
+  return head.length < content.length ? `${head}…` : head;
 };
 
 /** Tally how many matches fall into each section, in first-seen order. */