blume 0.6.7 → 0.8.0

package/src/components/islands/ask-ai.tsx

@@ -5,7 +5,7 @@ import type { FormEvent, KeyboardEvent as ReactKeyboardEvent } from "react";
 import { createPortal } from "react-dom";
 
 import type { UIStrings } from "../../core/i18n-ui.ts";
-import { joinBase, stripBase } from "./base-path.ts";
+import { joinBase, prefixBase, stripBase } from "./base-path.ts";
 
 interface ChatMessage {
   content: string;
@@ -43,6 +43,7 @@ const EMPTY_ICONS: AskIcons = {
 
 // English fallback so the island renders even if no dictionary is passed.
 const DEFAULT_ASK: UIStrings["ask"] = {
+  ai: "AI",
   clear: "Clear conversation",
   close: "Close",
   copy: "Copy conversation",
@@ -53,6 +54,7 @@ const DEFAULT_ASK: UIStrings["ask"] = {
   send: "Send",
   tip: "Tip: You can open and close chat with",
   title: "Ask AI",
+  you: "You",
 };
 
 let idCounter = 0;
@@ -72,12 +74,26 @@ const currentPath = (): string =>
 // GitHub-flavored markdown with soft line breaks, matching how the docs read.
 marked.setOptions({ breaks: true, gfm: true });
 
+// The model cites pages as base-less logical routes (`[Title](/route)`); rewrite
+// link targets to served URLs so citations resolve under `deployment.base`.
+// `prefixBase` leaves external URLs and fragments untouched and is idempotent.
+marked.use({
+  walkTokens: (token) => {
+    if (token.type === "link") {
+      token.href = prefixBase(import.meta.env.BASE_URL, token.href);
+    }
+  },
+});
+
 const renderMarkdown = (content: string): string =>
   DOMPurify.sanitize(marked.parse(content, { async: false }));
 
 const Glyph = ({ path, size = 16 }: { path: string; size?: number }) => (
   <svg
     aria-hidden="true"
+    // `path` is a trusted, server-resolved Lucide glyph body (inline SVG),
+    // not user content; it must be injected as markup to render the icon.
+    // oxlint-disable-next-line react/no-danger -- trusted server-resolved inline SVG glyph
     dangerouslySetInnerHTML={{ __html: path }}
     fill="none"
     height={size}
@@ -94,6 +110,14 @@ const Glyph = ({ path, size = 16 }: { path: string; size?: number }) => (
 // Stable empty default so an unset `suggestions` prop doesn't re-render.
 const EMPTY_SUGGESTIONS: Suggestion[] = [];
 
+// The toggle shortcut accepts both ⌘I and Ctrl+I; show the right modifier per
+// platform (same detection Search.astro uses for its ⌘K hint). Guarded so the
+// island still server-renders, where `navigator` doesn't exist; the hint itself
+// only renders client-side, inside the portaled panel.
+const IS_APPLE =
+  typeof navigator !== "undefined" &&
+  /mac|iphone|ipad|ipod/iu.test(navigator.platform);
+
 // Ghost icon button, matching the header's theme toggle and repo link.
 const TRIGGER_CLASS =
   "inline-flex size-9 cursor-pointer items-center justify-center rounded-full text-muted-foreground transition-colors hover:bg-muted hover:text-foreground";
@@ -117,7 +141,9 @@ const AskAI = ({
   strings?: UIStrings["ask"];
   suggestions?: Suggestion[];
 }) => {
-  const t = strings ?? DEFAULT_ASK;
+  // Merge per key (not `strings ?? …`) so a dictionary from a stale snapshot
+  // that predates newer keys still resolves every label to its English default.
+  const t = { ...DEFAULT_ASK, ...strings };
   const [mounted, setMounted] = useState(false);
   const [open, setOpen] = useState(false);
   const [input, setInput] = useState("");
@@ -125,8 +151,13 @@ const AskAI = ({
   const [busy, setBusy] = useState(false);
   const inputRef = useRef<HTMLTextAreaElement>(null);
   const scrollRef = useRef<HTMLDivElement>(null);
+  const triggerRef = useRef<HTMLButtonElement>(null);
+  // Where focus came from when the panel opened, restored on close.
+  const returnFocusRef = useRef<HTMLElement | null>(null);
 
-  // Portal target (document.body) only exists after mount; guards SSR.
+  // Portal target (document.body) only exists after mount; guards SSR. The
+  // one-time false→true flip is deliberate, so the initial `false` is required.
+  // oxlint-disable-next-line react/react-compiler, react-doctor/no-initialize-state -- deliberate post-mount portal guard
   useEffect(() => setMounted(true), []);
 
   // The search modal forwards its query so "Ask AI: <query>" carries straight in.
@@ -159,10 +190,24 @@ const AskAI = ({
   // Drive the desktop content push from a body attribute (see AskAI.astro CSS).
   useEffect(() => {
     if (open) {
+      returnFocusRef.current =
+        document.activeElement instanceof HTMLElement
+          ? document.activeElement
+          : null;
       document.body.dataset.blumeAsk = "open";
       inputRef.current?.focus();
     } else {
       delete document.body.dataset.blumeAsk;
+      // Return focus to the element that opened the panel (or the trigger when
+      // it's gone), so closing doesn't strand keyboard focus in an inert tree.
+      // `returnFocusRef` is only set on open, so initial mount is a no-op.
+      if (returnFocusRef.current) {
+        const target = returnFocusRef.current.isConnected
+          ? returnFocusRef.current
+          : triggerRef.current;
+        returnFocusRef.current = null;
+        target?.focus();
+      }
     }
     return () => {
       delete document.body.dataset.blumeAsk;
@@ -213,17 +258,19 @@ const AskAI = ({
       const decoder = new TextDecoder();
       let done = false;
       while (!done) {
-        // oxlint-disable-next-line no-await-in-loop -- sequential stream reads
+        // oxlint-disable-next-line no-await-in-loop, react-doctor/async-await-in-loop -- sequential stream consumption; iterations are not independent
         const chunk = await reader.read();
         ({ done } = chunk);
         if (chunk.value) {
           // Streaming mode: a multi-byte UTF-8 sequence split across chunks
           // must not flush as U+FFFD garbage.
+          // oxlint-disable-next-line react/react-compiler -- local streaming accumulator, spread into state below
           assistant.content += decoder.decode(chunk.value, { stream: true });
           setMessages((current) => [...current.slice(0, -1), { ...assistant }]);
         }
       }
     } catch {
+      // oxlint-disable-next-line react/react-compiler -- local streaming accumulator, spread into state below
       assistant.content = t.error;
       setMessages((current) => [...current.slice(0, -1), { ...assistant }]);
     } finally {
@@ -237,7 +284,13 @@ const AskAI = ({
   };
 
   const onInputKeyDown = (event: ReactKeyboardEvent<HTMLTextAreaElement>) => {
-    if (event.key === "Enter" && !event.shiftKey) {
+    // `isComposing` guards IME input: Enter confirming a CJK conversion must
+    // commit the text, not submit the question.
+    if (
+      event.key === "Enter" &&
+      !event.shiftKey &&
+      !event.nativeEvent.isComposing
+    ) {
       event.preventDefault();
       void runQuestion(input);
     }
@@ -245,7 +298,7 @@ const AskAI = ({
 
   const copyConversation = () => {
     const text = messages
-      .map((m) => `${m.role === "user" ? "You" : "AI"}: ${m.content}`)
+      .map((m) => `${m.role === "user" ? t.you : t.ai}: ${m.content}`)
       .join("\n\n");
     void navigator.clipboard?.writeText(text);
   };
@@ -256,6 +309,9 @@ const AskAI = ({
     <aside
       aria-hidden={open ? undefined : "true"}
       aria-label={t.title}
+      // The closed panel is only translated off-screen; `inert` drops its
+      // buttons/textarea from the tab order and the accessibility tree.
+      inert={!open}
       className={`fixed inset-y-0 end-0 z-[60] flex w-[var(--blume-ask-width)] flex-col border-border border-s bg-background shadow-2xl transition-transform duration-200 ease-out ${
         open ? "translate-x-0" : "translate-x-full rtl:-translate-x-full"
       }`}
@@ -268,7 +324,6 @@ const AskAI = ({
             className={ICON_BUTTON_CLASS}
             disabled={!hasMessages}
             onClick={copyConversation}
-            title={t.copy}
             type="button"
           >
             <Glyph path={icons.copy} />
@@ -278,7 +333,6 @@ const AskAI = ({
             className={ICON_BUTTON_CLASS}
             disabled={!hasMessages}
             onClick={() => setMessages([])}
-            title={t.clear}
             type="button"
           >
             <Glyph path={icons.clear} />
@@ -287,7 +341,6 @@ const AskAI = ({
             aria-label={t.close}
             className={ICON_BUTTON_CLASS}
             onClick={() => setOpen(false)}
-            title={t.close}
             type="button"
           >
             <Glyph path={icons.close} size={18} />
@@ -311,6 +364,8 @@ const AskAI = ({
                   {message.content ? (
                     // biome-ignore lint/security/noDangerouslySetInnerHtml: sanitized above
                     <div
+                      // renderMarkdown runs marked output through DOMPurify.sanitize.
+                      // oxlint-disable-next-line react/no-danger -- sanitized (DOMPurify) rendered-markdown output
                       dangerouslySetInnerHTML={{
                         __html: renderMarkdown(message.content),
                       }}
@@ -339,6 +394,7 @@ const AskAI = ({
                 {suggestion.icon && (
                   <span
                     className="shrink-0 text-muted-foreground [&_svg]:h-[18px] [&_svg]:w-[18px]"
+                    // oxlint-disable-next-line react/no-danger -- trusted server-resolved inline SVG glyph
                     dangerouslySetInnerHTML={{ __html: suggestion.icon }}
                   />
                 )}
@@ -348,7 +404,7 @@ const AskAI = ({
             <p className="mt-3 flex items-center gap-1.5 px-2 text-muted-foreground text-sm">
               {t.tip}
               <kbd className="rounded border border-border bg-muted px-1.5 py-0.5 font-sans text-xs">
-                ⌘
+                {IS_APPLE ? "⌘" : "Ctrl"}
               </kbd>
               <kbd className="rounded border border-border bg-muted px-1.5 py-0.5 font-sans text-xs">
                 I
@@ -364,7 +420,7 @@ const AskAI = ({
       >
         <textarea
           aria-label={t.label}
-          className="max-h-48 min-h-[5rem] w-full resize-none bg-transparent px-4 py-3.5 pe-14 text-foreground text-sm outline-none placeholder:text-muted-foreground"
+          className="max-h-48 min-h-[5rem] w-full resize-none bg-transparent px-4 py-3.5 pe-14 text-foreground text-sm pointer-coarse:text-base outline-none placeholder:text-muted-foreground"
           onChange={(event) => setInput(event.target.value)}
           onKeyDown={onInputKeyDown}
           placeholder={t.placeholder}
@@ -391,7 +447,7 @@ const AskAI = ({
         aria-label={t.title}
         className={TRIGGER_CLASS}
         onClick={() => setOpen((value) => !value)}
-        title={t.title}
+        ref={triggerRef}
         type="button"
       >
         <Glyph path={icons.chat} size={18} />

package/src/components/islands/base-path.ts

@@ -13,6 +13,34 @@ export const withTrailingSlash = (base: string): string =>
 export const joinBase = (base: string, path: string): string =>
   `${withTrailingSlash(base)}${path}`;
 
+/**
+ * Prefix a root-relative internal route with the deployment base
+ * (`/guide` under base `/sub` -> `/sub/guide`), so a rendered link points at the
+ * page's real served URL. External URLs, protocol-relative URLs, and fragments
+ * pass through untouched, and it's idempotent (a route already under the base is
+ * returned unchanged). This is applied only where a URL is *emitted* — the
+ * navigation model and active-route matching stay in base-less logical space.
+ */
+export const prefixBase = (base: string, route: string): string => {
+  if (!route.startsWith("/") || route.startsWith("//")) {
+    return route;
+  }
+  const trimmed = base.replace(/\/+$/u, "");
+  if (!trimmed || route === trimmed || route.startsWith(`${trimmed}/`)) {
+    return route;
+  }
+  return route === "/" ? trimmed : `${trimmed}${route}`;
+};
+
+/**
+ * {@link prefixBase} bound to the build-time `BASE_URL` (the resolved
+ * `deployment.base`). The ergonomic form for `.astro` templates — `href={
+ * withBase(route)}` — since `BASE_URL` is inlined by Vite wherever this module
+ * is bundled into the site.
+ */
+export const withBase = (route: string): string =>
+  prefixBase(import.meta.env.BASE_URL ?? "/", route);
+
 /**
  * A pathname with the deployment base stripped (`/docs/guide` -> `/guide`),
  * for page-context lookups against base-less document routes.

package/src/components/islands/hooks.ts

@@ -50,6 +50,10 @@ const readClientData = (): BlumeClientData | null => {
  */
 const useClientData = (): BlumeClientData | null => {
   const [data, setData] = useState<BlumeClientData | null>(null);
+  // Intentional post-mount hydration guard: `null` on the server and first
+  // client render so hydration matches, then the snapshot once mounted. The
+  // extra render is required; do not seed the initial value from the DOM.
+  // oxlint-disable-next-line react/react-compiler, react-doctor/no-initialize-state -- deliberate SSR hydration guard
   useEffect(() => setData(readClientData()), []);
   return data;
 };
@@ -85,19 +89,36 @@ export const useSearch = (): UseSearch => {
   const [results, setResults] = useState<SearchResult | null>(null);
   const [loading, setLoading] = useState(false);
   const searchFn = useRef<SearchFn | null>(null);
+  const generation = useRef(0);
 
+  // Retained for the compiler-off opt-out path (`react: { compiler: false }`):
+  // this useCallback keeps a stable `search` identity for consumers that use it
+  // as an effect/memo dependency. With the compiler on it's redundant but inert.
+  // oxlint-disable-next-line react-doctor/react-compiler-no-manual-memoization -- see above
   const search = useCallback<UseSearch["search"]>(async (query, options) => {
-    if (!searchFn.current) {
-      const { createSearch } = await import("blume:search-client");
-      searchFn.current = await createSearch();
-    }
+    // Stale-response guard, mirroring the built-in dialog's renderGeneration:
+    // provider responses can land out of order, so only the latest call may
+    // commit results or clear `loading` — otherwise the last response to land
+    // wins over the last query typed ("a" clobbering "ab").
+    generation.current += 1;
+    const { current } = generation;
+    // Before the lazy client import: the first search's heaviest phase is
+    // creating the provider client (index download), and it must show loading.
     setLoading(true);
     try {
+      if (!searchFn.current) {
+        const { createSearch } = await import("blume:search-client");
+        searchFn.current = await createSearch();
+      }
       const result = await searchFn.current(query, options);
-      setResults(result);
+      if (current === generation.current) {
+        setResults(result);
+      }
       return result;
     } finally {
-      setLoading(false);
+      if (current === generation.current) {
+        setLoading(false);
+      }
     }
   }, []);
 
@@ -120,6 +141,9 @@ export interface UseAskAI {
 
 const ASK_ENDPOINT = joinBase(import.meta.env.BASE_URL, "api/ask");
 
+/** Shown as the assistant's answer when the request fails or throws. */
+const ASK_ERROR = "Something went wrong answering that. Please try again.";
+
 /** The current route with the deployment base stripped, for page grounding. */
 const currentPath = (): string =>
   stripBase(import.meta.env.BASE_URL, window.location.pathname);
@@ -132,6 +156,10 @@ export const useAskAI = (): UseAskAI => {
   const [messages, setMessages] = useState<AskMessage[]>([]);
   const [loading, setLoading] = useState(false);
 
+  // Retained for the compiler-off opt-out path (`react: { compiler: false }`):
+  // preserves a stable `ask` identity for consumers that depend on it. With the
+  // compiler on it's redundant but inert.
+  // oxlint-disable-next-line react-doctor/react-compiler-no-manual-memoization -- see above
   const ask = useCallback<UseAskAI["ask"]>(
     async (question) => {
       const trimmed = question.trim();
@@ -157,8 +185,7 @@ export const useAskAI = (): UseAskAI => {
         if (!response.ok) {
           // An error body (JSON, HTML error page) must not stream in as the
           // assistant's answer.
-          assistant.content =
-            "Something went wrong answering that. Please try again.";
+          assistant.content = ASK_ERROR;
           setMessages([...history, { ...assistant }]);
           return;
         }
@@ -167,7 +194,7 @@ export const useAskAI = (): UseAskAI => {
         if (reader) {
           let done = false;
           while (!done) {
-            // oxlint-disable-next-line no-await-in-loop -- sequential stream reads
+            // oxlint-disable-next-line no-await-in-loop, react-doctor/async-await-in-loop -- sequential stream consumption; iterations are not independent
             const chunk = await reader.read();
             ({ done } = chunk);
             if (chunk.value) {
@@ -183,6 +210,11 @@ export const useAskAI = (): UseAskAI => {
             }
           }
         }
+      } catch {
+        // A thrown fetch (offline, DNS failure, CORS) must not strand the
+        // pre-appended empty assistant message as a stuck placeholder.
+        assistant.content = ASK_ERROR;
+        setMessages([...history, { ...assistant }]);
       } finally {
         setLoading(false);
       }
@@ -190,6 +222,9 @@ export const useAskAI = (): UseAskAI => {
     [loading, messages]
   );
 
+  // Retained for the compiler-off opt-out path (`react: { compiler: false }`):
+  // keeps a stable `reset` identity. With the compiler on it's redundant but inert.
+  // oxlint-disable-next-line react-doctor/react-compiler-no-manual-memoization -- see above
   const reset = useCallback(() => setMessages([]), []);
 
   return { ask, loading, messages, reset };

package/src/components/layout/Banner.astro

@@ -1,4 +1,7 @@
 ---
+import { EN_UI } from "../../core/i18n-ui.ts";
+import type { UIStrings } from "../../core/i18n-ui.ts";
+import { withBase } from "../islands/base-path.ts";
 import Icon from "../Icon.astro";
 
 // The site-wide announcement banner, shared by RootLayout and ReferenceLayout so
@@ -13,9 +16,15 @@ interface Props {
         key: string;
       }
     | null;
+  /** Localized banner labels. */
+  strings?: UIStrings["banner"];
 }
 
-const { banner } = Astro.props;
+const { banner, strings } = Astro.props;
+// Merge over the English baseline per key (rather than `strings ?? …`) so a
+// partial — or missing — strings object still resolves every label to a
+// default, matching the pattern PageFeedback and Search use.
+const b = { ...EN_UI.banner, ...strings };
 ---
 
 {
@@ -29,7 +38,7 @@ const { banner } = Astro.props;
       {banner.link && (
         <a
           class="inline-flex items-center gap-1 font-medium underline underline-offset-2"
-          href={banner.link.href}
+          href={withBase(banner.link.href)}
         >
           {banner.link.text}
           <Icon name="arrow-right" size={14} />
@@ -37,7 +46,7 @@ const { banner } = Astro.props;
       )}
       {banner.dismissible && (
         <button
-          aria-label="Dismiss announcement"
+          aria-label={b.dismiss}
           class="absolute end-1.5 inline-flex size-7 items-center justify-center rounded-full text-background/80 transition-colors hover:bg-white/10 hover:text-background dark:text-foreground/70 dark:hover:bg-foreground/10 dark:hover:text-foreground"
           data-blume-banner-dismiss
           type="button"

package/src/components/layout/Breadcrumbs.astro

@@ -1,4 +1,5 @@
 ---
+import { withBase } from "../islands/base-path.ts";
 import type { Crumb } from "./nav-utils.ts";
 
 interface Props {
@@ -25,7 +26,7 @@ const eyebrowCrumb = crumbs.length > 1 ? crumbs[crumbs.length - 2] : null;
       ]}
     >
       {eyebrowCrumb.route ? (
-        <a class="hover:text-foreground" href={eyebrowCrumb.route}>
+        <a class="hover:text-foreground" href={withBase(eyebrowCrumb.route)}>
           {eyebrowCrumb.label}
         </a>
       ) : (

package/src/components/layout/Favicon.astro

@@ -1,4 +1,5 @@
 ---
+import { withBase } from "../islands/base-path.ts";
 // Emits the icon <link>s for the document <head>: the favicon (rel="icon") and,
 // when the project ships one, the Apple touch icon (rel="apple-touch-icon").
 // Each href is either a URL to a file the project ships in public/, or a data
@@ -18,5 +19,5 @@ interface Props {
 const { appleIcon, favicon } = Astro.props;
 ---
 
-{favicon && <link href={favicon.href} rel="icon" type={favicon.type} />}
-{appleIcon && <link href={appleIcon.href} rel="apple-touch-icon" />}
+{favicon && <link href={withBase(favicon.href)} rel="icon" type={favicon.type} />}
+{appleIcon && <link href={withBase(appleIcon.href)} rel="apple-touch-icon" />}

package/src/components/layout/Header.astro

@@ -1,5 +1,7 @@
 ---
+import { withBase } from "../islands/base-path.ts";
 import type { ComponentOverride } from "../../core/define-components.ts";
+import { EN_UI } from "../../core/i18n-ui.ts";
 import type { UIStrings } from "../../core/i18n-ui.ts";
 import type { LocaleSwitchOption, Navigation } from "../../core/types.ts";
 import { GITHUB_MARK } from "../github-mark.ts";
@@ -36,6 +38,8 @@ interface Props {
   hasDrawer?: boolean;
   searchStrings?: UIStrings["search"];
   switcherStrings?: UIStrings["languageSwitcher"];
+  /** Localized chrome labels (nav toggle, sections, GitHub, theme toggle). */
+  navStrings?: UIStrings["nav"];
   localeSwitch?: LocaleSwitchOption[];
   /** Active locale for per-language search filtering. */
   searchLocale?: string;
@@ -58,11 +62,17 @@ const {
   hasDrawer = true,
   searchStrings,
   switcherStrings,
+  navStrings,
   localeSwitch,
   searchLocale,
   layout = {},
 } = Astro.props;
 
+// 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 n = { ...EN_UI.nav, ...navStrings };
+
 const LogoSlot = resolveSlot(layout.Logo, Logo);
 const SearchSlot = resolveSlot(layout.Search, Search);
 
@@ -108,7 +118,7 @@ const clickScript = `(()=>{const dr=()=>{const h=document.querySelector("[data-b
   {
     showNavToggle && (
       <button
-        aria-label="Toggle navigation"
+        aria-label={n.toggleNavigation}
         class={`${iconButton} lg:hidden`}
         data-blume-nav-toggle
         type="button"
@@ -129,7 +139,7 @@ const clickScript = `(()=>{const dr=()=>{const h=document.querySelector("[data-b
   }
   {
     navigation.tabs.length > 0 && (
-      <nav aria-label="Sections" class={tabsNavClass}>
+      <nav aria-label={n.sections} class={tabsNavClass}>
         {navigation.tabs.map((tab) => (
           <a
             aria-current={
@@ -139,7 +149,7 @@ const clickScript = `(()=>{const dr=()=>{const h=document.querySelector("[data-b
                 : undefined
             }
             class="rounded-full px-3 py-1.5 font-medium text-muted-foreground text-sm transition-colors hover:bg-muted hover:text-foreground aria-[current=page]:text-foreground"
-            href={tab.path}
+            href={withBase(tab.path)}
           >
             {tab.label}
           </a>
@@ -171,7 +181,7 @@ const clickScript = `(()=>{const dr=()=>{const h=document.querySelector("[data-b
     {
       navigation.repoUrl && (
         <a
-          aria-label="GitHub repository"
+          aria-label={n.githubRepository}
           class={iconButton}
           href={navigation.repoUrl}
           rel="noreferrer"
@@ -190,7 +200,7 @@ const clickScript = `(()=>{const dr=()=>{const h=document.querySelector("[data-b
       )
     }
     <button
-      aria-label="Toggle color theme"
+      aria-label={n.toggleTheme}
       class={iconButton}
       data-blume-theme-toggle
       type="button"

package/src/components/layout/LanguageSwitcher.astro

@@ -1,4 +1,5 @@
 ---
+import { withBase } from "../islands/base-path.ts";
 import type { LocaleSwitchOption } from "../../core/types.ts";
 import Icon from "../Icon.astro";
 
@@ -37,7 +38,7 @@ const menuRowClass =
           <a
             aria-current={option.current ? "true" : undefined}
             class={menuRowClass}
-            href={option.href}
+            href={withBase(option.href)}
             hreflang={option.code}
             lang={option.code}
           >

package/src/components/layout/Logo.astro

@@ -1,4 +1,5 @@
 ---
+import { withBase } from "../islands/base-path.ts";
 // The site brand: the logo mark (inline SVG so a `currentColor` mark follows the
 // theme, or light/dark `<img>` variants) followed by the site title, wrapped in
 // a link to the brand href. Extracted from the header so it can be replaced on
@@ -27,7 +28,7 @@ const brandText = logo?.text ?? site.title;
 
 <a
   class="inline-flex items-center gap-2 font-semibold text-base text-foreground"
-  href={brandHref}
+  href={withBase(brandHref)}
 >
   {
     logoSvg && (
@@ -42,11 +43,19 @@ const brandText = logo?.text ?? site.title;
     !logoSvg &&
       logoLight &&
       (logoLight === logoDark ? (
-        <img alt={logoAlt} class="h-5 w-auto" src={logoLight} />
+        <img alt={logoAlt} class="h-5 w-auto" src={withBase(logoLight)} />
       ) : (
         <>
-          <img alt={logoAlt} class="h-5 w-auto dark:hidden" src={logoLight} />
-          <img alt={logoAlt} class="hidden h-5 w-auto dark:block" src={logoDark} />
+          <img
+            alt={logoAlt}
+            class="h-5 w-auto dark:hidden"
+            src={withBase(logoLight)}
+          />
+          <img
+            alt={logoAlt}
+            class="hidden h-5 w-auto dark:block"
+            src={withBase(logoDark)}
+          />
         </>
       ))
   }

package/src/components/layout/NavSelector.astro

@@ -1,4 +1,5 @@
 ---
+import { withBase } from "../islands/base-path.ts";
 // A top-level navigation selector: a dropdown that switches
 // between partitions of the site — a product, a version, or any grouped set of
 // destinations (`navigation.selectors` in the config). Zero-JS, built on
@@ -50,7 +51,7 @@ const menuRowClass =
           <a
             aria-current={item.path === active?.path ? "true" : undefined}
             class={menuRowClass}
-            href={item.path}
+            href={withBase(item.path)}
           >
             {item.icon && <Icon class="mt-0.5" name={item.icon} size={16} />}
             <span class="flex-1">