blume 0.7.0 → 0.8.0

package/src/components/layout/PageActions.astro

@@ -68,6 +68,7 @@ const menuRowClass =
   class="mt-8 space-y-0.5 border-border border-t pt-4"
   data-blume-page-actions
   data-i18n-copied={a.copied}
+  data-i18n-generating={a.generating}
   data-mcp-name={mcpName ?? undefined}
   data-mcp-url={mcpUrl ?? undefined}
   data-md={mdPath}
@@ -98,7 +99,7 @@ const menuRowClass =
           class={`${rowClass} cursor-pointer list-none [&::-webkit-details-marker]:hidden`}
         >
           <Icon name="download" size={16} />
-          Export
+          {a.export}
           <Icon
             class="ms-auto transition-transform group-open:rotate-180"
             name="chevron-down"
@@ -112,14 +113,14 @@ const menuRowClass =
           {exportPdf && (
             <button class={menuRowClass} data-blume-export-pdf type="button">
               <Icon name="file" size={16} />
-              <span class="flex-1">Export to PDF</span>
+              <span class="flex-1">{a.exportPdf}</span>
             </button>
           )}
           {exportEpub && (
             <button class={menuRowClass} data-blume-export-epub type="button">
               <Icon name="book-open" size={16} />
               <span class="flex-1" data-blume-epub-label>
-                Export to EPUB
+                {a.exportEpub}
               </span>
             </button>
           )}
@@ -218,6 +219,8 @@ const menuRowClass =
 </div>
 
 <script>
+  import { prefixBase } from "../islands/base-path.ts";
+
   const CHAT_URLS: Record<string, (q: string) => string> = {
     chatgpt: (q) => `https://chatgpt.com/?hints=search&prompt=${q}`,
     claude: (q) => `https://claude.ai/new?q=${q}`,
@@ -317,8 +320,14 @@ hr { border: 0; border-top: 1px solid #ddd; margin: 2em 0; }`;
       }
     });
 
-    const md = root.getAttribute("data-md") ?? "";
+    // `data-md` is the base-less logical route; the raw-markdown endpoint is a
+    // generated page route, so it's served under the deployment base like any
+    // other page. Prefix at emit time (the Search-island pattern).
+    const mdRoute = root.getAttribute("data-md") ?? "";
+    const md = prefixBase(import.meta.env.BASE_URL, mdRoute);
     const copiedLabel = root.getAttribute("data-i18n-copied") || "Copied!";
+    const generatingLabel =
+      root.getAttribute("data-i18n-generating") || "Generating…";
     const absolute = new URL(md, location.origin).href;
     const query = encodeURIComponent(
       `Read ${absolute} so I can ask you questions about this page.`
@@ -414,6 +423,9 @@ hr { border: 0; border-top: 1px solid #ddd; margin: 2em 0; }`;
       ?.addEventListener("click", async () => {
         try {
           const response = await fetch(md);
+          if (!response.ok) {
+            throw new Error(`Fetching ${md} failed (${response.status})`);
+          }
           await navigator.clipboard.writeText(await response.text());
           if (label) {
             label.textContent = copiedLabel;
@@ -421,8 +433,9 @@ hr { border: 0; border-top: 1px solid #ddd; margin: 2em 0; }`;
               label.textContent = original;
             }, 1500);
           }
-        } catch {
-          // Clipboard or fetch unavailable; nothing to do.
+        } catch (error) {
+          // Clipboard or fetch unavailable; don't flash "Copied!" untruthfully.
+          console.error("[blume] Copy as Markdown failed", error);
         }
       });
 
@@ -432,6 +445,9 @@ hr { border: 0; border-top: 1px solid #ddd; margin: 2em 0; }`;
 
     const epubButton = root.querySelector("[data-blume-export-epub]");
     const epubLabel = root.querySelector("[data-blume-epub-label]");
+    // Captured once — inside the handler a click during a generation would
+    // capture and permanently restore "Generating…".
+    const epubReset = epubLabel?.textContent ?? "";
     epubButton?.addEventListener("click", async () => {
       const article = document.querySelector("#blume-content article");
       if (!article) {
@@ -439,9 +455,8 @@ hr { border: 0; border-top: 1px solid #ddd; margin: 2em 0; }`;
       }
       const heading = document.querySelector("#blume-content h1");
       const title = heading?.textContent?.trim() || document.title;
-      const reset = epubLabel?.textContent ?? "Export to EPUB";
       if (epubLabel) {
-        epubLabel.textContent = "Generating…";
+        epubLabel.textContent = generatingLabel;
       }
       try {
         // Browser bundle: avoids Node built-ins and returns a Blob. Lazy-loaded
@@ -461,7 +476,7 @@ hr { border: 0; border-top: 1px solid #ddd; margin: 2em 0; }`;
             ? result
             : new Blob([result], { type: "application/epub+zip" });
         const slug =
-          md
+          mdRoute
             .replace(/\.md$/u, "")
             .replace(/^\//u, "")
             .replace(/\//gu, "-") || "index";
@@ -479,7 +494,7 @@ hr { border: 0; border-top: 1px solid #ddd; margin: 2em 0; }`;
         console.error("[blume] EPUB export failed", error);
       } finally {
         if (epubLabel) {
-          epubLabel.textContent = reset;
+          epubLabel.textContent = epubReset;
         }
       }
     });

package/src/components/layout/PageLayout.astro

@@ -110,6 +110,10 @@ const clientDataJson = clientData
   : null;
 
 const strings = ui ?? EN_UI;
+// Merge over the English defaults so a label 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 };
 // Filter search to the active language only when the site is multi-locale.
 const searchLocale =
   localeSwitch && localeSwitch.length > 1 ? locale : undefined;
@@ -125,19 +129,23 @@ const ogSlug = route === "/" ? "index" : route.slice(1);
 // Absolute URLs carry the deployment base too (`site + base + route`), since the
 // page is served under it. `withBase` handles a root base as a no-op.
 const basedRoute = withBase(route);
+// The schema accepts a trailing-slash site URL (`https://docs.example.com/`);
+// strip it before joining with the root-relative route so canonical/og URLs
+// don't come out double-slashed — the catch-all strips it the same way.
+const siteBase = siteUrl ? siteUrl.replace(/\/$/u, "") : null;
 const resolvedCanonical =
   canonical ??
-  (siteUrl ? `${siteUrl}${basedRoute === "/" ? "" : basedRoute}` : null);
+  (siteBase ? `${siteBase}${basedRoute === "/" ? "" : basedRoute}` : null);
 // An explicit `ogImage` wins. A root-relative path (e.g. an image dropped in
 // `public/`) is resolved against the site URL so crawlers get an absolute
 // `og:image`; an already-absolute URL passes through untouched. Otherwise fall
 // back to the generated OG card for this route.
 const absolutizeOgImage = (value: string): string =>
-  value.startsWith("/") && siteUrl ? `${siteUrl}${withBase(value)}` : value;
+  value.startsWith("/") && siteBase ? `${siteBase}${withBase(value)}` : value;
 const resolvedOgImage = ogImage
   ? absolutizeOgImage(ogImage)
-  : ogEnabled && siteUrl
-    ? `${siteUrl}${withBase(`/og/${ogSlug}.png`)}`
+  : ogEnabled && siteBase
+    ? `${siteBase}${withBase(`/og/${ogSlug}.png`)}`
     : null;
 
 const initialThemeScript = themeInitScript(themeMode);
@@ -178,12 +186,13 @@ const bannerScript = banner?.dismissible
       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} />
     <Header
       askEnabled={askEnabled}
       hasSidebar={false}
       localeSwitch={localeSwitch}
       logo={logo}
+      navStrings={navStrings}
       navigation={navigation}
       route={route}
       searchEnabled={searchEnabled}
@@ -205,10 +214,11 @@ const bannerScript = banner?.dismissible
       navigation.tabs.length > 0 && (
         <>
           <aside
-            aria-label="Navigation"
+            aria-label={navStrings.navigation}
             class="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:hidden"
+            data-blume-nav-drawer
           >
-            <nav aria-label="Sections">
+            <nav aria-label={navStrings.sections}>
               <ul class="m-0 list-none p-0">
                 {navigation.tabs.map((tab) => (
                   <li>
@@ -230,7 +240,7 @@ const bannerScript = banner?.dismissible
             </nav>
           </aside>
           <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"
@@ -252,6 +262,33 @@ const bannerScript = banner?.dismissible
       // Dev-only: friendly hint after a React island hydration mismatch;
       // tree-shaken out of production builds.
       import "./hydration-hint.ts";
+
+      // The closed tabs drawer is only translated off-canvas, so its links
+      // would stay in the tab order. Mirror the header's `data-blume-nav-open`
+      // toggle into `inert`/`aria-hidden` below `lg` (64rem), matching the
+      // breakpoint where the drawer is display-hidden anyway.
+      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"],
+        });
+      }
     </script>
   </body>
 </html>

package/src/components/layout/ReferenceLayout.astro

@@ -1,5 +1,7 @@
 ---
 import "blume:theme";
+import { EN_UI } from "../../core/i18n-ui.ts";
+import type { UIStrings } from "../../core/i18n-ui.ts";
 import type { Navigation } from "../../core/types.ts";
 import Analytics from "./Analytics.astro";
 import Banner from "./Banner.astro";
@@ -50,6 +52,8 @@ interface Props {
   fontCssVars?: string[];
   searchEnabled: boolean;
   pageTitle: string;
+  /** Resolved UI dictionary; English baseline when omitted. */
+  ui?: UIStrings;
 }
 
 const {
@@ -65,8 +69,11 @@ const {
   fontCssVars,
   searchEnabled,
   pageTitle,
+  ui,
 } = Astro.props;
 
+const strings = ui ?? EN_UI;
+
 // Set the theme before paint so the navbar never flashes the wrong colors
 // (mirrors RootLayout's pre-paint script).
 const initialThemeScript = `(()=>{const m=${JSON.stringify(themeMode)};const s=localStorage.getItem("blume-theme");const sys=matchMedia("(prefers-color-scheme: dark)").matches?"dark":"light";document.documentElement.dataset.theme=s??(m==="system"?sys:m);})();`;
@@ -90,7 +97,7 @@ const bannerScript = banner?.dismissible
     <Analytics analytics={analytics} />
   </head>
   <body class="bg-background font-sans text-foreground antialiased">
-    <Banner banner={banner} />
+    <Banner banner={banner} strings={strings.banner} />
     <Header
       hasDrawer={false}
       hasSidebar={false}

package/src/components/layout/RootLayout.astro

@@ -206,6 +206,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;
@@ -345,12 +351,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 +368,7 @@ const bannerScript = banner?.dismissible
       route={page.route}
       searchEnabled={searchEnabled}
       searchLocale={searchLocale}
+      navStrings={navStrings}
       searchStrings={strings.search}
       site={site}
       switcherStrings={strings.languageSwitcher}
@@ -371,7 +380,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 +395,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 +444,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,14 +476,26 @@ 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>
@@ -542,7 +567,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 +584,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 +670,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,13 @@ 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-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 +67,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 +124,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 +196,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 +208,11 @@ 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";
+      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 +223,14 @@ 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.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 +273,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(
@@ -301,6 +330,7 @@ const kbd = "rounded border border-border bg-muted px-1 py-0.5 font-mono";
         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 +338,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 +359,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 +400,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 +437,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 +475,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);
@@ -464,13 +536,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);