blume 1.0.3 → 1.1.0

package/src/components/content/Prompt.astro

@@ -59,7 +59,15 @@ const secondaryButton =
               data-blume-prompt-copy
               type="button"
             >
-              <span data-blume-prompt-copy-label>Copy prompt</span>
+              {/* Both labels share one grid cell so the button is always sized
+                  to the wider ("Copy prompt") — swapping to "Copied" on copy
+                  can't resize it and shift the description beside it. */}
+              <span class="grid *:col-start-1 *:row-start-1 *:text-center">
+                <span data-blume-prompt-copy-idle>Copy prompt</span>
+                <span aria-hidden="true" class="invisible" data-blume-prompt-copy-done>
+                  Copied
+                </span>
+              </span>
             </button>
           )}
           {enabledActions.has("cursor") && (
@@ -99,6 +107,13 @@ const secondaryButton =
       const copy = this.querySelector<HTMLButtonElement>(
         "[data-blume-prompt-copy]"
       );
+      const idle = copy?.querySelector<HTMLElement>(
+        "[data-blume-prompt-copy-idle]"
+      );
+      const done = copy?.querySelector<HTMLElement>(
+        "[data-blume-prompt-copy-done]"
+      );
+      let resetTimer: ReturnType<typeof setTimeout> | undefined;
       copy?.addEventListener("click", async () => {
         const text = promptText();
         if (!text) {
@@ -110,18 +125,15 @@ const secondaryButton =
           return;
         }
 
-        const label = copy.querySelector<HTMLElement>(
-          "[data-blume-prompt-copy-label]"
-        );
-        if (!label) {
-          return;
-        }
-        // Remember the real label once — capturing at click time would
-        // capture "Copied" on a double-click and stick until reload.
-        label.dataset.blumeLabel ??= label.textContent ?? "Copy prompt";
-        label.textContent = "Copied";
-        setTimeout(() => {
-          label.textContent = label.dataset.blumeLabel ?? "Copy prompt";
+        // Toggle visibility rather than swapping text: both labels occupy the
+        // same grid cell, so the button width never changes. Clearing the timer
+        // keeps the "Copied" state 1.5s past the last of several rapid clicks.
+        clearTimeout(resetTimer);
+        idle?.classList.add("invisible");
+        done?.classList.remove("invisible");
+        resetTimer = setTimeout(() => {
+          idle?.classList.remove("invisible");
+          done?.classList.add("invisible");
         }, 1500);
       });
     }

package/src/components/content/Tabs.astro

@@ -4,6 +4,20 @@ interface Props {
   defaultTabIndex?: number;
   dropdown?: boolean;
   hash?: boolean | "false" | "true";
+  /**
+   * Render borderless — a tab strip on a full-width rule with the content
+   * flowing beneath as prose — instead of the default bordered box. Reads as
+   * page-level navigation rather than an isolated widget; pair with `param` for
+   * shareable, multiple-per-page tabs.
+   */
+  inline?: boolean;
+  /**
+   * Sync the active tab to this URL query-param key instead of the hash. Each
+   * group owns its own param, so several `Tabs` can share a page and every
+   * selection is deep-linkable (`?install=windows`). Give each group a unique
+   * `param`; it takes precedence over `hash`.
+   */
+  param?: string;
   sync?: boolean;
 }
 
@@ -12,34 +26,53 @@ const {
   defaultTabIndex = 0,
   dropdown = false,
   hash = true,
+  inline = false,
+  param,
   sync = true,
 } = Astro.props;
 
 // MDX string attributes (`hash="false"` from generated markup) must read as
 // their boolean meaning — the string "false" is truthy.
 const hashEnabled = String(hash) !== "false";
+// The dropdown (select) affordance belongs to the boxed layout; inline always
+// renders a tab strip.
+const useDropdown = dropdown && !inline;
 ---
 
 <blume-tabs
-  class="not-prose my-6 block overflow-hidden rounded-blume border border-border bg-background"
+  class:list={[
+    "my-6 block",
+    inline
+      ? ""
+      : "not-prose overflow-hidden rounded-blume border border-border bg-background",
+  ]}
   data-border-bottom={borderBottom ? "true" : "false"}
   data-default-tab-index={defaultTabIndex}
-  data-dropdown={dropdown ? "true" : "false"}
+  data-dropdown={useDropdown ? "true" : "false"}
   data-hash={hashEnabled ? "true" : "false"}
+  data-param={param}
   data-sync={sync ? "true" : "false"}
 >
-  <div class:list={[dropdown ? "" : "overflow-x-auto"]}>
+  <div
+    class:list={[
+      inline ? "not-prose" : "",
+      useDropdown ? "" : "overflow-x-auto",
+    ]}
+  >
     <div
       class:list={[
-        dropdown || borderBottom ? "border-border border-b" : "",
-        dropdown ? "p-3" : "flex gap-4 px-3",
+        useDropdown || borderBottom ? "border-border border-b" : "",
+        useDropdown ? "p-3" : inline ? "flex gap-4" : "flex gap-4 px-3",
       ]}
       data-blume-tablist
-      role={dropdown ? undefined : "tablist"}
+      role={useDropdown ? undefined : "tablist"}
     >
     </div>
   </div>
-  <div data-blume-tab-content>
+  <div
+    class:list={[inline ? "pt-4 [&>[data-blume-tab-panel]]:p-0!" : ""]}
+    data-blume-tab-content
+  >
     <slot />
   </div>
 </blume-tabs>
@@ -114,7 +147,7 @@ const hashEnabled = String(hash) !== "false";
         if (this.#syncEnabled()) {
           document.addEventListener(SYNC_EVENT, this.#sync);
         }
-        window.addEventListener("hashchange", this.#hashChange);
+        this.#addUrlListener();
         return;
       }
       this.dataset.blumeTabsReady = "true";
@@ -173,12 +206,13 @@ const hashEnabled = String(hash) !== "false";
       if (this.#syncEnabled()) {
         document.addEventListener(SYNC_EVENT, this.#sync);
       }
-      window.addEventListener("hashchange", this.#hashChange);
+      this.#addUrlListener();
     }
 
     disconnectedCallback() {
       document.removeEventListener(SYNC_EVENT, this.#sync);
-      window.removeEventListener("hashchange", this.#hashChange);
+      window.removeEventListener("hashchange", this.#urlChange);
+      window.removeEventListener("popstate", this.#urlChange);
     }
 
     activate(index: number, sync: boolean, updateHash: boolean) {
@@ -201,8 +235,18 @@ const hashEnabled = String(hash) !== "false";
         this.#select.value = String(index);
       }
       const id = panelId(activePanel);
-      if (updateHash && id && this.#hashEnabled()) {
-        history.replaceState(null, "", `#${encodeURIComponent(id)}`);
+      if (updateHash && id) {
+        const param = this.#paramName();
+        if (param) {
+          // Query-param mode: write only this group's key, so several groups on
+          // one page each deep-link independently. replaceState (not push) keeps
+          // the shareable URL current without stacking a history entry per click.
+          const url = new URL(window.location.href);
+          url.searchParams.set(param, id);
+          history.replaceState(history.state, "", url);
+        } else if (this.#hashEnabled()) {
+          history.replaceState(null, "", `#${encodeURIComponent(id)}`);
+        }
       }
       if (sync && this.#syncEnabled()) {
         document.dispatchEvent(
@@ -239,8 +283,29 @@ const hashEnabled = String(hash) !== "false";
       return true;
     }
 
+    #activateByParam() {
+      const param = this.#paramName();
+      if (!param) {
+        return false;
+      }
+      const value = new URL(window.location.href).searchParams.get(param);
+      if (!value) {
+        return false;
+      }
+      const index = this.#panels.findIndex((panel) => panelId(panel) === value);
+      if (index === -1) {
+        return false;
+      }
+
+      this.activate(index, false, false);
+      return true;
+    }
+
     #initialIndex() {
-      if (this.#activateByHash()) {
+      const activated = this.#paramName()
+        ? this.#activateByParam()
+        : this.#activateByHash();
+      if (activated) {
         return this.#panels.findIndex((panel) => !panel.classList.contains("hidden"));
       }
       return boundedIndex(
@@ -278,6 +343,20 @@ const hashEnabled = String(hash) !== "false";
       return this.dataset.hash !== "false";
     }
 
+    #paramName() {
+      return this.dataset.param || null;
+    }
+
+    // Query-param changes don't fire `hashchange`; they surface through history
+    // navigation (`popstate`). Listen to whichever channel this group syncs on.
+    #addUrlListener() {
+      if (this.#paramName()) {
+        window.addEventListener("popstate", this.#urlChange);
+      } else {
+        window.addEventListener("hashchange", this.#urlChange);
+      }
+    }
+
     #sync = (event: Event) => {
       const title = (event as CustomEvent<{ title?: string }>).detail?.title;
       if (title) {
@@ -285,8 +364,12 @@ const hashEnabled = String(hash) !== "false";
       }
     };
 
-    #hashChange = () => {
-      this.#activateByHash();
+    #urlChange = () => {
+      if (this.#paramName()) {
+        this.#activateByParam();
+      } else {
+        this.#activateByHash();
+      }
     };
   }
 

package/src/components/layout/Breadcrumbs.astro

@@ -31,7 +31,7 @@ const eyebrowCrumb = crumbs.length > 1 ? crumbs[crumbs.length - 2] : null;
       aria-label={n.breadcrumb}
       class:list={[
         "mb-2 text-muted-foreground text-sm",
-        wide ? "max-w-none" : "mx-auto max-w-[42rem]",
+        wide ? "max-w-none" : "mx-auto max-w-content",
       ]}
     >
       {eyebrowCrumb.route ? (

package/src/components/layout/Header.astro

@@ -10,7 +10,7 @@ import { GITHUB_MARK } from "../github-mark.ts";
 import Icon from "../Icon.astro";
 import LanguageSwitcher from "./LanguageSwitcher.astro";
 import Logo from "./Logo.astro";
-import { isUnderPath } from "./nav-utils.ts";
+import { activeTabForRoute } from "./nav-utils.ts";
 import NavSelector from "./NavSelector.astro";
 import { resolveSlot } from "./overrides.ts";
 import Search from "./Search.astro";
@@ -94,6 +94,7 @@ const SearchSlot = resolveSlot(layout.Search, Search);
 // PageLayout) it's a tabs-only drawer the layout renders — so the button is also
 // needed whenever there are tabs to reveal.
 const showNavToggle = hasDrawer && (hasSidebar || navigation.tabs.length > 0);
+const activeTab = activeTabForRoute(navigation.tabs, route);
 // Where the header's inline tab bar appears. With a sidebar it shares the `md`
 // breakpoint with the docs drawer; without one, the tabs-only drawer is the sole
 // mobile nav below `lg`, so the inline tabs wait until `lg` to avoid duplicating
@@ -155,14 +156,9 @@ const clickScript = `(()=>{const dr=()=>{const h=document.querySelector("[data-b
       <nav aria-label={n.sections} class={tabsNavClass}>
         {navigation.tabs.map((tab) => (
           <a
-            aria-current={
-              route === tab.path ||
-              (tab.path !== "/" && isUnderPath(route, tab.path))
-                ? "page"
-                : undefined
-            }
+            aria-current={tab === activeTab ? "page" : 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={withBase(tab.path)}
+            href={withBase(tab.href ?? tab.path)}
           >
             {tab.label}
           </a>
@@ -186,6 +182,7 @@ const clickScript = `(()=>{const dr=()=>{const h=document.querySelector("[data-b
         askEnabled={askEnabled}
         locale={searchLocale}
         navigation={navigation}
+        popularPages={data.config.search.popular}
         strings={searchStrings}
       />
     )

package/src/components/layout/Logo.astro

@@ -18,6 +18,8 @@ const { site, logo } = Astro.props;
 const logoSvg = logo?.svg;
 const logoLight = logo?.light;
 const logoDark = logo?.dark ?? logo?.light;
+const logoLightDimensions = logo?.dimensions?.light;
+const logoDarkDimensions = logo?.dimensions?.dark ?? logo?.dimensions?.light;
 const logoAlt = logo?.alt ?? "";
 const brandHref = logo?.href ?? "/";
 // Wordmark beside the mark: the configured `logo.text`, or the site title when
@@ -43,18 +45,28 @@ const brandText = logo?.text ?? site.title;
     !logoSvg &&
       logoLight &&
       (logoLight === logoDark ? (
-        <img alt={logoAlt} class="h-5 w-auto" src={withBase(logoLight)} />
+        <img
+          alt={logoAlt}
+          class="h-5 w-auto"
+          height={logoLightDimensions?.height}
+          src={withBase(logoLight)}
+          width={logoLightDimensions?.width}
+        />
       ) : (
         <>
           <img
             alt={logoAlt}
             class="h-5 w-auto dark:hidden"
+            height={logoLightDimensions?.height}
             src={withBase(logoLight)}
+            width={logoLightDimensions?.width}
           />
           <img
             alt={logoAlt}
             class="hidden h-5 w-auto dark:block"
+            height={logoDarkDimensions?.height}
             src={withBase(logoDark)}
+            width={logoDarkDimensions?.width}
           />
         </>
       ))

package/src/components/layout/PageFeedback.astro

@@ -15,12 +15,12 @@ const { strings } = Astro.props;
 const f = { ...EN_UI.feedback, ...strings };
 
 const buttonClass =
-  "inline-flex items-center gap-2 rounded-full border border-border px-4 py-2 text-foreground text-sm transition-colors hover:border-foreground";
+  "inline-flex items-center gap-2 rounded-blume border border-border px-4 py-2 text-foreground text-sm transition-colors hover:border-foreground";
 ---
 
 <section
   aria-label={f.question}
-  class="mx-auto mt-12 flex max-w-[42rem] items-center justify-between gap-4 border-border border-t pt-6"
+  class="mx-auto mt-12 flex max-w-content items-center justify-between gap-4 border-border border-t pt-6"
   data-blume-page-feedback
 >
   <p class="text-muted-foreground text-sm">{f.question}</p>

package/src/components/layout/PageLayout.astro

@@ -39,7 +39,7 @@ import Favicon from "./Favicon.astro";
 import Fonts from "./Fonts.astro";
 import { BANNER_INIT_SCRIPT, THEME_INIT_SCRIPT } from "./head-scripts.ts";
 import Header from "./Header.astro";
-import { isUnderPath } from "./nav-utils.ts";
+import { activeTabForRoute } from "./nav-utils.ts";
 
 interface Props {
   site: { title: string; description?: string };
@@ -137,6 +137,7 @@ const searchLocale =
 const pageTitle = page?.title ?? site.title;
 const description = page?.description ?? site.description;
 const route = page?.route ?? "/";
+const activeTab = activeTabForRoute(navigation.tabs, route);
 
 // Derive canonical + og:image from the site URL the same way the catch-all does
 // for content pages, so a custom page gets both for free. The matching OG card
@@ -185,7 +186,11 @@ const bannerKey = banner?.dismissible ? banner.key : null;
     <title>{pageTitle}</title>
     <Favicon appleIcon={appleIcon} favicon={favicon} />
     <Fonts cssVars={fontCssVars ?? []} />
-    {resolvedCanonical && <link href={resolvedCanonical} rel="canonical" />}
+    {/* Google warns against pairing a canonical with noindex — the canonical
+        says "index that URL", the robots meta says "distrust this page". */}
+    {resolvedCanonical && !noindex && (
+      <link href={resolvedCanonical} rel="canonical" />
+    )}
     {noindex && <meta content="noindex" name="robots" />}
     {description && <meta content={description} name="description" />}
     <meta content="website" property="og:type" />
@@ -267,14 +272,9 @@ const bannerKey = banner?.dismissible ? banner.key : null;
                 {navigation.tabs.map((tab) => (
                   <li>
                     <a
-                      aria-current={
-                        route === tab.path ||
-                        (tab.path !== "/" && isUnderPath(route, tab.path))
-                          ? "page"
-                          : undefined
-                      }
+                      aria-current={tab === activeTab ? "page" : undefined}
                       class="block rounded-[0.65rem] px-2.5 py-1.5 font-medium text-muted-foreground text-sm transition-colors hover:bg-muted hover:text-foreground aria-[current=page]:bg-muted aria-[current=page]:text-foreground"
-                      href={withBase(tab.path)}
+                      href={withBase(tab.href ?? tab.path)}
                     >
                       {tab.label}
                     </a>

package/src/components/layout/Pagination.astro

@@ -26,19 +26,19 @@ const s = { ...EN_UI.page, ...strings };
   (prev || next) && (
     <nav
       aria-label={s.pagination}
-      class="mx-auto mt-12 flex max-w-[42rem] justify-between gap-4 border-border border-t pt-6 max-md:flex-col"
+      class="mx-auto mt-12 flex max-w-content justify-between gap-4 border-border border-t pt-6 max-md:flex-col"
     >
       {prev ? (
         <a
-          class="flex max-w-[48%] flex-1 items-center gap-2 rounded-full border border-border px-4 py-3 text-foreground transition-colors hover:border-foreground max-md:max-w-full"
+          class="flex max-w-[48%] flex-1 items-center gap-2 rounded-blume border border-border px-4 py-3 text-foreground transition-colors hover:border-foreground max-md:max-w-full"
           href={withBase(prev.route)}
         >
           <Icon class="rtl:-scale-x-100" name="arrow-left" size={16} />
-          <span>
+          <span class="min-w-0">
             <span class="block text-muted-foreground text-xs max-md:hidden">
               {s.previous}
             </span>
-            <span class="block font-medium">{prev.label}</span>
+            <span class="block truncate font-medium">{prev.label}</span>
           </span>
         </a>
       ) : (
@@ -46,14 +46,14 @@ const s = { ...EN_UI.page, ...strings };
       )}
       {next && (
         <a
-          class="ms-auto flex max-w-[48%] flex-1 items-center justify-end gap-2 rounded-full border border-border px-4 py-3 text-end text-foreground transition-colors hover:border-foreground max-md:max-w-full"
+          class="ms-auto flex max-w-[48%] flex-1 items-center justify-end gap-2 rounded-blume border border-border px-4 py-3 text-end text-foreground transition-colors hover:border-foreground max-md:max-w-full"
           href={withBase(next.route)}
         >
-          <span>
+          <span class="min-w-0">
             <span class="block text-muted-foreground text-xs max-md:hidden">
               {s.next}
             </span>
-            <span class="block font-medium">{next.label}</span>
+            <span class="block truncate font-medium">{next.label}</span>
           </span>
           <Icon class="rtl:-scale-x-100" name="arrow-right" size={16} />
         </a>

package/src/components/layout/RootLayout.astro

@@ -27,10 +27,10 @@ import { BANNER_INIT_SCRIPT, THEME_INIT_SCRIPT } from "./head-scripts.ts";
 import Header from "./Header.astro";
 import Icon from "../Icon.astro";
 import {
+  activeTabForRoute,
   findBreadcrumbs,
   flattenPages,
   getPagination,
-  isUnderPath,
   sidebarForRoute,
 } from "./nav-utils.ts";
 import NavTree from "./NavTree.astro";
@@ -261,7 +261,7 @@ if (isBare) {
 } else if (isApiOperation) {
   gridClass = "lg:grid-cols-[17.5rem_minmax(0,1fr)]";
 }
-let articleClass = "prose mx-auto max-w-[42rem]";
+let articleClass = "prose mx-auto max-w-content";
 if (isBare) {
   articleClass = "prose mx-auto max-w-[54rem]";
 } else if (isApiOperation) {
@@ -307,6 +307,7 @@ const mcpUrl =
 // active tab's section, so a multi-section site drills each tab into its own
 // pages. Without tabs — or on a route under none — this is the full sidebar.
 const sidebar = sidebarForRoute(navigation.sidebar, navigation.tabs, page.route);
+const activeTab = activeTabForRoute(navigation.tabs, page.route);
 const crumbs = findBreadcrumbs(sidebar, page.route);
 const { prev, next } = getPagination(flattenPages(sidebar), page.route);
 
@@ -344,7 +345,9 @@ const bannerKey = banner?.dismissible ? banner.key : null;
     <title>{pageTitle}</title>
     <Favicon favicon={favicon} appleIcon={appleIcon} />
     <Fonts cssVars={fontCssVars ?? []} />
-    {canonical && <link rel="canonical" href={canonical} />}
+    {/* Google warns against pairing a canonical with noindex — the canonical
+        says "index that URL", the robots meta says "distrust this page". */}
+    {canonical && !noindex && <link rel="canonical" href={canonical} />}
     {
       localeAlternates?.map((alt) => (
         <link href={alt.href} hreflang={alt.hreflang} rel="alternate" />
@@ -526,14 +529,9 @@ const bannerKey = banner?.dismissible ? banner.key : null;
                 {navigation.tabs.map((tab) => (
                   <li>
                     <a
-                      aria-current={
-                        page.route === tab.path ||
-                        (tab.path !== "/" && isUnderPath(page.route, tab.path))
-                          ? "page"
-                          : undefined
-                      }
+                      aria-current={tab === activeTab ? "page" : undefined}
                       class="block rounded-[0.65rem] px-2.5 py-1.5 font-medium text-muted-foreground text-sm transition-colors hover:bg-muted hover:text-foreground aria-[current=page]:bg-muted aria-[current=page]:text-foreground"
-                      href={withBase(tab.path)}
+                      href={withBase(tab.href ?? tab.path)}
                     >
                       {tab.label}
                     </a>
@@ -596,7 +594,7 @@ const bannerKey = banner?.dismissible ? banner.key : null;
                 route={page.route}
               />
               {formattedLastModified && (
-                <p class="mx-auto mt-10 max-w-[42rem] text-muted-foreground text-sm">
+                <p class="mx-auto mt-10 max-w-content text-muted-foreground text-sm">
                   {strings.page.lastUpdated} {formattedLastModified}
                 </p>
               )}

package/src/components/layout/Search.astro

@@ -2,6 +2,7 @@
 import { EN_UI } from "../../core/i18n-ui.ts";
 import type { UIStrings } from "../../core/i18n-ui.ts";
 import type { Navigation } from "../../core/types.ts";
+import { resolveIcon } from "../../theme/icons.ts";
 import Icon from "../Icon.astro";
 import { flattenPages } from "./nav-utils.ts";
 
@@ -13,19 +14,43 @@ import { flattenPages } from "./nav-utils.ts";
 interface Props {
   askEnabled?: boolean;
   navigation?: Navigation;
+  /** Curated empty-state pages; falls back to the first sidebar pages when empty or omitted. */
+  popularPages?: { icon?: string; label: string; route: string }[];
   strings?: UIStrings["search"];
   /** Active locale to filter results to; omitted disables locale filtering. */
   locale?: string;
 }
 
-const { askEnabled = false, navigation, strings, locale } = Astro.props;
+const { askEnabled = false, navigation, popularPages, strings, locale } =
+  Astro.props;
 // Merge over the English baseline per key (rather than `strings ?? …`) so a
 // partial — or empty `{}` — strings object still resolves every label to a
 // default, matching the pattern PageActions uses for its own dictionary.
 const s = { ...EN_UI.search, ...strings };
 
-// Pages shown in the empty state, before the user has typed anything.
-const popular = navigation ? flattenPages(navigation.sidebar).slice(0, 6) : [];
+// Icons resolve to inline SVG here (`theme/icons.ts` is a server-only module —
+// far too large to ship to the browser), so the island gets ready-to-render
+// markup rather than a name it can't resolve. Same approach as AskAI.astro.
+// A name outside the set falls through to the island's own file glyph.
+const iconSvg = (name: string | undefined): string | undefined => {
+  const resolved = name ? resolveIcon(name) : null;
+  return resolved
+    ? `<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" viewBox="${resolved.viewBox}" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">${resolved.body}</svg>`
+    : undefined;
+};
+
+// Pages shown in the empty state, before the user has typed anything. Only
+// curated entries carry an icon; sidebar-derived rows keep the file glyph.
+const popular =
+  popularPages && popularPages.length > 0
+    ? popularPages.map((page) => ({
+        icon: iconSvg(page.icon),
+        label: page.label,
+        route: page.route,
+      }))
+    : navigation
+      ? flattenPages(navigation.sidebar).slice(0, 6)
+      : [];
 
 const kbd = "rounded border border-border bg-muted px-1 py-0.5 font-mono";
 ---
@@ -58,7 +83,7 @@ const kbd = "rounded border border-border bg-muted px-1 py-0.5 font-mono";
 
   <dialog
     aria-label={s.label}
-    class="m-auto h-[min(480px,90vh)] w-[min(62.5rem,94vw)] flex-col overflow-hidden rounded-blume border border-border bg-background/80 p-0 text-foreground shadow-2xl outline-none backdrop-blur-xl backdrop:bg-black/30 open:flex"
+    class="mx-auto mt-[8vh] mb-auto h-[min(480px,90dvh)] w-[min(62.5rem,94vw)] flex-col overflow-hidden rounded-blume border border-border bg-background/80 p-0 text-foreground shadow-2xl outline-none backdrop-blur-xl backdrop:bg-black/30 open:flex sm:mt-auto"
     data-blume-search-dialog
   >
     <div
@@ -166,6 +191,8 @@ const kbd = "rounded border border-border bg-muted px-1 py-0.5 font-mono";
     }
 
     interface PopularPage {
+      /** Pre-resolved inline SVG from the server; absent falls back to `file`. */
+      icon?: string;
       label: string;
       route: string;
     }
@@ -501,7 +528,7 @@ const kbd = "rounded border border-border bg-muted px-1 py-0.5 font-mono";
         if (this.popular.length > 0) {
           const group = this.addGroup(this.popularMsg);
           for (const page of this.popular) {
-            const item = this.createLinkRow(page.route, page.label);
+            const item = this.createLinkRow(page.route, page.label, page.icon);
             group.appendChild(item.el);
             this.selectables.push(item);
           }
@@ -590,13 +617,15 @@ const kbd = "rounded border border-border bg-muted px-1 py-0.5 font-mono";
         return item;
       }
 
-      createLinkRow(url: string, label: string): Selectable {
+      createLinkRow(url: string, label: string, icon?: string): Selectable {
         const el = document.createElement("a");
         const href = prefixBase(import.meta.env.BASE_URL, url);
         el.href = href;
         el.className = ROW_CLASS;
+        // `icon` is server-resolved markup from the bundled icon set, not
+        // author HTML — the label still goes through `escapeHtml`.
         el.innerHTML = `
-          <span class="mt-0.5 shrink-0 text-muted-foreground">${svg("file")}</span>
+          <span class="mt-0.5 shrink-0 text-muted-foreground">${icon ?? svg("file")}</span>
           <span class="flex-1">
             <span class="block truncate font-normal text-foreground text-sm">${escapeHtml(label)}</span>
           </span>`;

package/src/components/layout/TableOfContents.astro

@@ -19,7 +19,7 @@ const { headings, title, variant } = Astro.props;
 
 {
   headings.length > 0 && variant === "mobile" && (
-    <details class="group mx-auto mb-6 max-w-[42rem] rounded-blume border border-border xl:hidden">
+    <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>
         <Icon

package/src/components/layout/nav-utils.ts

@@ -80,14 +80,16 @@ export const isUnderPath = (route: string, base: string): boolean =>
   base === "/" || route === base || route.startsWith(`${base}/`);
 
 /**
- * The tab whose `path` is the longest prefix of `route`, mirroring the header's
- * active-tab highlight. The root tab (`/`) is skipped — it spans everything and
- * so never scopes the sidebar.
+ * The tab whose `path` is the longest prefix of `route`. The root tab (`/`)
+ * acts as the fallback when no more specific tab matches.
  */
-const activeTab = (tabs: NavTab[], route: string): NavTab | null => {
+export const activeTabForRoute = (
+  tabs: NavTab[],
+  route: string
+): NavTab | null => {
   let match: NavTab | null = null;
   for (const tab of tabs) {
-    if (tab.path === "/" || !isUnderPath(route, tab.path)) {
+    if (!isUnderPath(route, tab.path)) {
       continue;
     }
     if (!match || tab.path.length > match.path.length) {
@@ -187,8 +189,8 @@ export const sidebarForRoute = (
   tabs: NavTab[],
   route: string
 ): NavNode[] => {
-  const tab = activeTab(tabs, route);
-  if (tab) {
+  const tab = activeTabForRoute(tabs, route);
+  if (tab && tab.path !== "/") {
     return sectionChildren(sidebar, tab.path) ?? [];
   }
   const scoped = withoutTabSections(sidebar, tabs);