@dogsbay/docs-layout 0.2.0-beta.9 → 0.2.0-beta.90

package/src/SearchDialog.astro

@@ -28,10 +28,26 @@ import type { TaxonomyDisplay } from "@dogsbay/types";
 
 interface Props {
   /**
-   * Path prefix where Pagefind's index lives. Default: "/pagefind/".
-   * Override when a site uses a non-root base path (e.g. "/docs/pagefind/").
+   * Path where Pagefind's index lives, e.g. `/pagefind/` or
+   * `/<repo>/pagefind/` for subpath-mounted deploys. NO DEFAULT —
+   * a host-root default would silently 404 on subpath deploys
+   * (GH Pages project pages, multi-mount Cloudflare). The
+   * format-astro emitter passes the combined-prefix-aware URL;
+   * manual instantiations must do the same. When undefined, the
+   * search dialog throws on first open with a clear console error.
    */
   pagefindUrl?: string;
+  /**
+   * URL of the site's `nav.json` (typically `${basePath}/_dogsbay/nav.json`).
+   * Used to render hierarchical facets in document order: when the
+   * `category` facet (or any taxonomy flagged `hierarchical: true`)
+   * is segment-encoded — i.e. its values are individual path segments
+   * not slash-joined — the tree shape is derived from nav. Without
+   * `navUrl`, hierarchical segment-encoded facets fall back to a flat
+   * list (still functional, just no tree structure). Slash-encoded
+   * taxonomies don't need nav and build trees from their values directly.
+   */
+  navUrl?: string;
   /** Placeholder text for the search input */
   placeholder?: string;
   /**
@@ -44,7 +60,8 @@ interface Props {
 }
 
 const {
-  pagefindUrl = "/pagefind/",
+  pagefindUrl,
+  navUrl,
   placeholder = "Search docs...",
   taxonomyDisplay,
 } = Astro.props;
@@ -53,6 +70,7 @@ const {
 <dialog
   data-search-dialog
   data-pagefind-url={pagefindUrl}
+  data-nav-url={navUrl}
   data-taxonomy-display={taxonomyDisplay ? JSON.stringify(taxonomyDisplay) : ""}
   class="fixed left-1/2 top-[10vh] z-50 w-[calc(100vw-2rem)] max-w-4xl -translate-x-1/2 rounded-xl border border-border bg-popover p-0 text-popover-foreground shadow-2xl backdrop:bg-black/40 backdrop:backdrop-blur-sm"
 >
@@ -156,13 +174,19 @@ const {
     shapeFacets,
     resolveFacetLabel,
     resolveFacetTitle,
+    sortFacetNames,
     filterStateToUrlParams,
     parseFiltersFromUrl,
     filterStateToPagefindFilters,
     toggleFilter,
     countActiveFilters,
+    buildFacetTree,
+    computeTreeState,
+    toggleTreeNode,
     type FacetMap,
+    type FacetTreeNode,
     type FilterState,
+    type NavLike,
     type TaxonomyDisplayMap,
   } from "./search-facets.js";
 
@@ -177,10 +201,15 @@ const {
     meta: { title?: string };
     sub_results?: Array<{ title: string; url: string; excerpt: string }>;
   };
+  // Filter values match what filterStateToPagefindFilters emits:
+  // each facet wrapped in `{any: [...]}` for OR-within-facet semantics.
+  // Pagefind also accepts other operator shapes (`all`/`none`/`not`,
+  // bare strings, bare arrays) but we only emit the `any` form.
+  type PagefindFilterValue = { any: string[] };
   type PagefindModule = {
     search(
       query: string,
-      options?: { filters?: Record<string, string[]> },
+      options?: { filters?: Record<string, PagefindFilterValue> },
     ): Promise<{ results: PagefindResult[] }>;
     filters(): Promise<Record<string, Record<string, number>>>;
   };
@@ -204,6 +233,15 @@ const {
     let filters: FilterState = {};
     let availableFacets: FacetMap = {};
 
+    // Nav data cached after first fetch — used to derive the
+    // segment-encoded hierarchical-facet tree (the auto-`category`
+    // case). Null while pending or absent. The fetch fires lazily
+    // the first time renderFacets() encounters a hierarchical facet,
+    // not eagerly on dialog open, so sites without hierarchical
+    // facets never pay for it.
+    let navData: NavLike[] | null = null;
+    let loadingNav: Promise<void> | null = null;
+
     // Display config baked into a data attribute by the Astro
     // template — parsed lazily.
     const taxonomyDisplay: TaxonomyDisplayMap = (() => {
@@ -218,7 +256,22 @@ const {
     async function ensurePagefindLoaded() {
       if (pagefind) return;
       if (loadingPagefind) return loadingPagefind;
-      const url = (dialog!.dataset.pagefindUrl ?? "/pagefind/") + "pagefind.js";
+      // pagefindUrl is required — a "/pagefind/" fallback would
+      // silently 404 on subpath-mounted deploys (GH Pages project
+      // pages, multi-mount Cloudflare). The emitter always passes
+      // a combined-prefix-aware value via data-pagefind-url. If it's
+      // missing the page wasn't built through format-astro and the
+      // caller forgot to pass it.
+      const dataUrl = dialog!.dataset.pagefindUrl;
+      if (!dataUrl) {
+        console.error(
+          "[dogsbay] SearchDialog: pagefindUrl prop missing. " +
+          "Pass the combined-prefix path (e.g. '/<base>/pagefind/') " +
+          "from your DocsLayout instantiation.",
+        );
+        return;
+      }
+      const url = dataUrl + "pagefind.js";
       loadingPagefind = (async () => {
         try {
           const mod = (await import(/* @vite-ignore */ url)) as PagefindModule;
@@ -237,6 +290,49 @@ const {
       return loadingPagefind;
     }
 
+    /**
+     * Lazy nav.json fetch, kicked off the first time a hierarchical
+     * facet is rendered. Mirrors the pattern in `docs-nav-client.ts` —
+     * one fetch per session, `same-origin` credentials so cookied
+     * mounts work, module-level cache.
+     *
+     * When the fetch resolves we re-call `renderFacets()` so the
+     * previously-flat segment-encoded facet upgrades to its tree
+     * shape — without this, a slow nav fetch would leave the facets
+     * stuck on the flat fallback until the user toggled a filter.
+     *
+     * Network errors are logged and swallowed; the helper's flat
+     * fallback keeps the dialog functional.
+     */
+    async function ensureNavLoaded() {
+      if (navData !== null) return;
+      if (loadingNav) return loadingNav;
+      const url = dialog!.dataset.navUrl;
+      if (!url) return; // navUrl not provided — flat fallback stays
+      loadingNav = (async () => {
+        try {
+          const res = await fetch(url, { credentials: "same-origin" });
+          if (!res.ok) throw new Error(`nav.json fetch failed: ${res.status}`);
+          const data = (await res.json()) as unknown;
+          navData = Array.isArray(data) ? (data as NavLike[]) : [];
+          // Re-render so hierarchical segment-encoded facets pick up
+          // the nav shape. Cheap — no Pagefind round-trip, just a
+          // DOM rebuild from `availableFacets`.
+          if (Object.keys(availableFacets).length > 0) {
+            renderFacets();
+          }
+        } catch (err) {
+          console.warn(
+            "[dogsbay] failed to load nav.json (hierarchical facets fall back to flat list):",
+            err,
+          );
+          // Mark as loaded-with-empty so we don't keep retrying.
+          navData = [];
+        }
+      })();
+      return loadingNav;
+    }
+
     function escapeHtml(s: string): string {
       return s
         .replace(/&/g, "&amp;")
@@ -313,54 +409,171 @@ const {
       resultsBox!.innerHTML = html;
     }
 
+    /**
+     * Hierarchical-facet caches, rebuilt on every renderFacets() so
+     * they stay aligned with the current filter state + available
+     * facets. The trees are the source for `value → node` lookups
+     * during click handling (parent click expands selection to all
+     * descendants — needs the node to know what to add).
+     */
+    const facetTrees = new Map<string, FacetTreeNode[]>();
+    const facetNodesByValue = new Map<string, Map<string, FacetTreeNode>>();
+
+    /**
+     * Decide whether a facet renders as a tree. `category` defaults
+     * to hierarchical (auto-derived path segments are the canonical
+     * use case); explicit override via `taxonomyDisplay[name].hierarchical`
+     * wins both ways.
+     */
+    function isHierarchicalFacet(name: string): boolean {
+      const flag = taxonomyDisplay[name]?.hierarchical;
+      if (typeof flag === "boolean") return flag;
+      return name === "category";
+    }
+
+    /**
+     * Flatten a tree into a `value → node` map so the click handler
+     * can look up the clicked node without re-walking the tree.
+     */
+    function indexTree(nodes: FacetTreeNode[]): Map<string, FacetTreeNode> {
+      const out = new Map<string, FacetTreeNode>();
+      const visit = (n: FacetTreeNode): void => {
+        out.set(n.value, n);
+        for (const c of n.children) visit(c);
+      };
+      for (const r of nodes) visit(r);
+      return out;
+    }
+
+    /**
+     * Recursive HTML for one tree node. Synthetic parents (`hasValue:
+     * false`) render as a clickable group header — checking them
+     * still cascades to descendants via toggleTreeNode. Indent scales
+     * with `node.depth`.
+     */
+    function renderTreeNode(name: string, node: FacetTreeNode): string {
+      const state = computeTreeState(node, name, filters);
+      const id = `facet-${name}-${node.value}`.replace(/[^a-z0-9-]/gi, "-");
+      const indent = node.depth * 12;
+      const label = escapeHtml(node.label);
+      const countText = node.hasValue ? `${node.count}` : "";
+      const stateAttr =
+        state === "checked" ? "checked" : state === "indeterminate" ? 'data-tree-indeterminate="true"' : "";
+      const childrenHtml = node.children
+        .map((c) => renderTreeNode(name, c))
+        .join("");
+      return `
+        <li>
+          <label
+            for="${id}"
+            class="flex cursor-pointer items-center gap-2 rounded-md px-2 py-1 hover:bg-accent"
+            style="padding-left: ${0.5 + indent / 16}rem"
+          >
+            <input
+              type="checkbox"
+              id="${id}"
+              data-facet-name="${escapeHtml(name)}"
+              data-facet-value="${escapeHtml(node.value)}"
+              data-tree-node="true"
+              ${state === "checked" ? "checked" : ""}
+              ${state === "indeterminate" ? 'data-tree-indeterminate="true"' : ""}
+              class="size-3.5 rounded border-border accent-primary"
+            />
+            <span class="flex-1 truncate">${label}</span>
+            <span class="text-xs text-muted-foreground">${countText}</span>
+          </label>
+          ${childrenHtml ? `<ul class="space-y-0.5">${childrenHtml}</ul>` : ""}
+        </li>
+      `;
+    }
+
     /**
      * Build the facets sidebar. Runs once after Pagefind discovers
      * filters, then again whenever filter state changes (so checkbox
      * `checked` reflects current selections). When the corpus has no
      * filters, the sidebar stays hidden — single-column layout.
+     *
+     * Branches per facet: hierarchical taxonomies (and the built-in
+     * `category` default) render as a tree; flat taxonomies keep the
+     * original checkbox-list shape. The hierarchical path falls back
+     * to a flat list automatically when segment-encoded values lack a
+     * `nav` source — preserves render-ability until Phase 3 wires the
+     * nav.json fetch.
      */
     function renderFacets() {
-      const facetNames = Object.keys(availableFacets);
+      const facetNames = sortFacetNames(
+        Object.keys(availableFacets),
+        taxonomyDisplay,
+      );
       if (facetNames.length === 0) {
         facetsBox!.classList.add("hidden");
         return;
       }
       facetsBox!.classList.remove("hidden");
 
+      facetTrees.clear();
+      facetNodesByValue.clear();
+
       const activeCount = countActiveFilters(filters);
       const clearAll = activeCount > 0
         ? `<button type="button" data-clear-filters class="mb-3 w-full rounded-md border border-border px-2 py-1 text-xs text-muted-foreground transition-colors hover:bg-accent hover:text-foreground">Clear all (${activeCount})</button>`
         : "";
 
+      let needsNav = false;
       const groups = facetNames
         .map((name) => {
           const entries = availableFacets[name];
           const title = escapeHtml(resolveFacetTitle(name));
-          const items = entries
-            .map((entry) => {
-              const checked = (filters[name] ?? []).includes(entry.value);
-              const label = escapeHtml(
-                resolveFacetLabel(name, entry.value, taxonomyDisplay),
-              );
-              const id = `facet-${name}-${entry.value}`.replace(/[^a-z0-9-]/gi, "-");
-              return `
-                <li>
-                  <label for="${id}" class="flex cursor-pointer items-center gap-2 rounded-md px-2 py-1 hover:bg-accent">
-                    <input
-                      type="checkbox"
-                      id="${id}"
-                      data-facet-name="${escapeHtml(name)}"
-                      data-facet-value="${escapeHtml(entry.value)}"
-                      ${checked ? "checked" : ""}
-                      class="size-3.5 rounded border-border accent-primary"
-                    />
-                    <span class="flex-1 truncate">${label}</span>
-                    <span class="text-xs text-muted-foreground">${entry.count}</span>
-                  </label>
-                </li>
-              `;
-            })
-            .join("");
+          const hierarchical = isHierarchicalFacet(name);
+
+          let items: string;
+          if (hierarchical) {
+            // Every hierarchical facet wants nav.json — slash-encoded
+            // for sort order at each depth (so docs follow nav rather
+            // than count-desc), segment-encoded for the tree structure
+            // itself. Without nav, slash-encoded still renders a tree
+            // (using values alone) but in count-desc order, which is
+            // wrong on corpora where one branch dwarfs the rest
+            // (openshift's rest_api section). Fire ensureNavLoaded()
+            // any time a hierarchical facet renders with navData still
+            // null — when it resolves, renderFacets re-runs and
+            // upgrades the sort.
+            if (navData === null) needsNav = true;
+            const tree = buildFacetTree(name, entries, {
+              display: taxonomyDisplay,
+              nav: navData ?? undefined,
+            });
+            facetTrees.set(name, tree);
+            facetNodesByValue.set(name, indexTree(tree));
+            items = tree.map((n) => renderTreeNode(name, n)).join("");
+          } else {
+            items = entries
+              .map((entry) => {
+                const checked = (filters[name] ?? []).includes(entry.value);
+                const label = escapeHtml(
+                  resolveFacetLabel(name, entry.value, taxonomyDisplay),
+                );
+                const id = `facet-${name}-${entry.value}`.replace(/[^a-z0-9-]/gi, "-");
+                return `
+                  <li>
+                    <label for="${id}" class="flex cursor-pointer items-center gap-2 rounded-md px-2 py-1 hover:bg-accent">
+                      <input
+                        type="checkbox"
+                        id="${id}"
+                        data-facet-name="${escapeHtml(name)}"
+                        data-facet-value="${escapeHtml(entry.value)}"
+                        ${checked ? "checked" : ""}
+                        class="size-3.5 rounded border-border accent-primary"
+                      />
+                      <span class="flex-1 truncate">${label}</span>
+                      <span class="text-xs text-muted-foreground">${entry.count}</span>
+                    </label>
+                  </li>
+                `;
+              })
+              .join("");
+          }
+
           return `
             <fieldset class="mb-3">
               <legend class="mb-1 text-xs font-semibold uppercase tracking-wide text-muted-foreground">${title}</legend>
@@ -371,6 +584,20 @@ const {
         .join("");
 
       facetsBox!.innerHTML = clearAll + groups;
+
+      // `indeterminate` is a JS property, not an HTML attribute —
+      // can't set via innerHTML. Walk new checkboxes and set it
+      // post-paint so the visual tri-state matches state.
+      const indet = facetsBox!.querySelectorAll<HTMLInputElement>(
+        'input[type="checkbox"][data-tree-indeterminate="true"]',
+      );
+      for (const el of Array.from(indet)) el.indeterminate = true;
+
+      // Lazy nav fetch — fired only when at least one hierarchical
+      // segment-encoded facet rendered with the flat fallback. The
+      // fetch's resolution handler calls renderFacets() again so the
+      // facet upgrades to its real tree shape without user action.
+      if (needsNav) void ensureNavLoaded();
     }
 
     async function runSearch(query: string) {
@@ -475,13 +702,26 @@ const {
     });
 
     // Facet checkbox toggling — event delegation on the sidebar.
+    // Tree nodes route through toggleTreeNode (parent click expands
+    // to all descendants); flat checkboxes use toggleFilter as before.
+    // We compute state from the pre-click filter, NOT from the
+    // checkbox's post-click `checked` value — the browser has already
+    // flipped it by the time `change` fires, so reading it would
+    // invert our toggle direction for indeterminate parents.
     facetsBox.addEventListener("change", (e) => {
       const target = e.target as HTMLInputElement;
       if (target.tagName !== "INPUT" || target.type !== "checkbox") return;
       const name = target.dataset.facetName;
       const value = target.dataset.facetValue;
       if (!name || !value) return;
-      filters = toggleFilter(filters, name, value);
+      if (target.dataset.treeNode === "true") {
+        const node = facetNodesByValue.get(name)?.get(value);
+        if (!node) return;
+        const currentState = computeTreeState(node, name, filters);
+        filters = toggleTreeNode(filters, name, node, currentState);
+      } else {
+        filters = toggleFilter(filters, name, value);
+      }
       renderFacets();
       runSearch(input!.value);
       syncUrl();

package/src/docs-nav-client.ts

@@ -0,0 +1,265 @@
+/**
+ * Client-side sidebar nav hydration.
+ *
+ * Fetches `/_dogsbay/nav.json` once per session, renders the tree DOM
+ * to mirror `@dogsbay/ui/sidebar/SidebarNavTree.astro`'s structure,
+ * and re-highlights the current page on each Astro view-transition
+ * page-load.
+ *
+ * Design constraints:
+ *   - DOM output matches SidebarNavTree exactly (same tags, classes,
+ *     data-attributes) so Tailwind's compiled CSS styles us correctly
+ *     and any sidebar-system selectors (e.g. `data-sidebar="nav-tree"`
+ *     hooks) keep working.
+ *   - Filter by `version` / `locale` matches `nav-filter.ts`'s SSR
+ *     filter so a multi-axis site renders the same nav as `ssr-full`
+ *     mode (without the multiplicative HTML cost).
+ *   - One fetch per session. The `nav.json` URL is served with
+ *     `Cache-Control: immutable` by Astro's static build (it lives
+ *     under `public/_dogsbay/`), so the browser cache holds it across
+ *     navigations.
+ *
+ * See plans/client-rendered-nav.md.
+ */
+import { filterNavByAxis } from "./nav-filter.js";
+
+interface NavItem {
+  label: string;
+  href?: string;
+  icon?: string;
+  children?: NavItem[];
+}
+
+/**
+ * Module-level cache so multiple page loads in the same SPA session
+ * share the same fetched nav data. Cleared by re-loads (full page
+ * navigations) but Astro's view transitions re-execute the script
+ * module without reloading the page — so on view-transition the
+ * cached promise is reused and no extra fetch fires.
+ */
+let navPromise: Promise<NavItem[]> | null = null;
+
+function fetchNav(url: string): Promise<NavItem[]> {
+  if (!navPromise) {
+    navPromise = fetch(url, { credentials: "same-origin" }).then((r) => {
+      if (!r.ok) throw new Error(`nav.json fetch failed: ${r.status}`);
+      return r.json() as Promise<NavItem[]>;
+    });
+  }
+  return navPromise;
+}
+
+function normalize(path: string): string {
+  return path.replace(/\/$/, "") || "/";
+}
+
+function hasActiveDescendant(item: NavItem, current: string): boolean {
+  if (item.href && normalize(item.href) === current) return true;
+  return item.children?.some((c) => hasActiveDescendant(c, current)) ?? false;
+}
+
+/**
+ * Render a single nav item into a `<li>` DOM node. Matches
+ * SidebarNavTree's per-level class set exactly so styling stays in
+ * sync. Padding is computed from `level` the same way (`8 + level*12`
+ * pixels) so indentation lines up across the same render.
+ */
+function renderItem(item: NavItem, current: string, level: number): HTMLLIElement {
+  const li = document.createElement("li");
+  li.dataset.sidebar = "nav-tree-item";
+
+  const active = item.href ? normalize(item.href) === current : false;
+  const hasChildren = !!item.children && item.children.length > 0;
+  const padLeft = `${8 + level * 12}px`;
+  const heightClass = level === 0 ? "h-8" : "h-7";
+
+  if (hasChildren) {
+    const details = document.createElement("details");
+    if (active || hasActiveDescendant(item, current)) details.open = true;
+
+    const summary = document.createElement("summary");
+    summary.className = [
+      "flex w-full min-w-0 cursor-pointer items-center gap-2 rounded-md text-sm text-sidebar-foreground outline-none [list-style:none] ring-sidebar-ring hover:bg-sidebar-accent hover:text-sidebar-accent-foreground focus-visible:ring-2 [&::-webkit-details-marker]:hidden",
+      heightClass,
+      active ? "bg-sidebar-accent font-medium text-sidebar-accent-foreground" : "",
+    ]
+      .filter(Boolean)
+      .join(" ");
+    summary.style.paddingLeft = padLeft;
+    if (item.href) summary.dataset.navHref = item.href;
+    if (active) summary.dataset.active = "true";
+
+    // Chevron SVG — matches SidebarNavTree's rotation-on-open via CSS
+    // (`details[open] > summary [data-chevron] { transform: rotate(90deg); }`).
+    summary.innerHTML =
+      '<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="size-4 shrink-0 transition-transform duration-200" data-chevron aria-hidden="true"><polyline points="9 18 15 12 9 6"/></svg>';
+
+    if (item.icon) {
+      const iconSpan = document.createElement("span");
+      iconSpan.className = "shrink-0 [&>svg]:size-4";
+      iconSpan.innerHTML = item.icon;
+      summary.appendChild(iconSpan);
+    }
+
+    const label = document.createElement("span");
+    label.className = "truncate";
+    label.textContent = item.label;
+    summary.appendChild(label);
+
+    details.appendChild(summary);
+
+    // Recurse — nested `<ul>` mirrors SidebarNavTree's `<Astro.self>`.
+    const childUl = document.createElement("ul");
+    childUl.className = "flex min-w-0 flex-col";
+    childUl.dataset.sidebar = "nav-tree";
+    childUl.dataset.level = String(level + 1);
+    for (const child of item.children!) {
+      childUl.appendChild(renderItem(child, current, level + 1));
+    }
+    details.appendChild(childUl);
+
+    li.appendChild(details);
+  } else {
+    const a = document.createElement("a");
+    a.href = item.href || "#";
+    a.className = [
+      "flex w-full min-w-0 items-center gap-2 rounded-md text-sm text-sidebar-foreground outline-none ring-sidebar-ring hover:bg-sidebar-accent hover:text-sidebar-accent-foreground focus-visible:ring-2",
+      heightClass,
+      active ? "bg-sidebar-accent font-medium text-sidebar-accent-foreground" : "",
+    ]
+      .filter(Boolean)
+      .join(" ");
+    a.style.paddingLeft = padLeft;
+    if (active) a.dataset.active = "true";
+    if (item.href) a.dataset.navHref = item.href;
+
+    // Spacer to align leaf text with branch text (which has a chevron).
+    const spacer = document.createElement("span");
+    spacer.className = "size-4 shrink-0";
+    a.appendChild(spacer);
+
+    if (item.icon) {
+      const iconSpan = document.createElement("span");
+      iconSpan.className = "shrink-0 [&>svg]:size-4";
+      iconSpan.innerHTML = item.icon;
+      a.appendChild(iconSpan);
+    }
+
+    const label = document.createElement("span");
+    label.className = "truncate";
+    label.textContent = item.label;
+    a.appendChild(label);
+
+    li.appendChild(a);
+  }
+
+  return li;
+}
+
+function renderTree(items: NavItem[], current: string, root: HTMLElement): void {
+  const ul = document.createElement("ul");
+  ul.className =
+    "flex min-w-0 flex-col w-full group-data-[collapsible=icon]:hidden";
+  ul.dataset.sidebar = "nav-tree";
+  ul.dataset.level = "0";
+  for (const item of items) {
+    ul.appendChild(renderItem(item, current, 0));
+  }
+  // Replace skeleton in one DOM op so there's no flash of partial state.
+  root.replaceChildren(ul);
+  root.removeAttribute("aria-busy");
+}
+
+/**
+ * Re-highlight the active item without rebuilding the whole tree.
+ * Used on `astro:page-load` when view transitions land on a new
+ * route — we re-toggle the `data-active` attribute and re-apply the
+ * active classes, then expand the new active branch's ancestors.
+ *
+ * Cheaper than a full re-render (no fetch, no DOM rebuild). For
+ * the wider hydration loop we still re-render when a brand-new nav
+ * structure is needed (e.g. switching versions), but path-only
+ * navigation just re-highlights.
+ */
+function rehighlight(root: HTMLElement, current: string): void {
+  const ACTIVE_CLASSES = [
+    "bg-sidebar-accent",
+    "font-medium",
+    "text-sidebar-accent-foreground",
+  ];
+  const items = root.querySelectorAll<HTMLElement>("[data-nav-href]");
+  for (const el of Array.from(items)) {
+    const href = el.dataset.navHref;
+    const active = !!href && normalize(href) === current;
+    if (active) {
+      el.dataset.active = "true";
+      el.classList.add(...ACTIVE_CLASSES);
+    } else {
+      delete el.dataset.active;
+      el.classList.remove(...ACTIVE_CLASSES);
+    }
+  }
+  // Expand ancestors of the new active item.
+  const active = root.querySelector<HTMLElement>('[data-active="true"]');
+  if (active) {
+    let parent: HTMLElement | null = active.parentElement;
+    while (parent) {
+      if (parent.tagName === "DETAILS") {
+        (parent as HTMLDetailsElement).open = true;
+      }
+      parent = parent.parentElement;
+    }
+  }
+}
+
+/**
+ * Public entry point. Called once from `<DocsNavClient />`'s inline
+ * script tag. Idempotent — subsequent calls (e.g. from view
+ * transitions) are no-ops once the tree has been rendered; they just
+ * re-highlight against the new pathname.
+ */
+export async function hydrateDocsNav(): Promise<void> {
+  const root = document.getElementById("docs-nav-root");
+  if (!root) return;
+
+  const navUrl = root.dataset.navUrl;
+  if (!navUrl) {
+    console.warn("docs-nav: missing data-nav-url");
+    return;
+  }
+  const current = normalize(root.dataset.currentPath || location.pathname);
+  const basePath = root.dataset.basePath || "";
+  const version = root.dataset.version || undefined;
+  const locale = root.dataset.locale || undefined;
+
+  try {
+    const nav = await fetchNav(navUrl);
+    const filtered = filterNavByAxis(nav, {
+      basePath: basePath || "/docs",
+      version: version || undefined,
+      locale: locale || undefined,
+    });
+    renderTree(filtered, current, root);
+  } catch (err) {
+    console.error("docs-nav: hydration failed", err);
+    root.setAttribute("aria-busy", "false");
+    // Keep skeleton so layout doesn't collapse on failure; a real
+    // user will reload or follow the noscript link.
+  }
+}
+
+// Re-run on view transitions. astro:page-load fires both on initial
+// load and after each ClientRouter transition; the module-level
+// `navPromise` cache makes the post-transition path a fast
+// highlight-only pass without re-fetching.
+document.addEventListener("astro:page-load", () => {
+  const root = document.getElementById("docs-nav-root");
+  if (!root) return;
+  // If tree is already rendered (no aria-busy), just re-highlight.
+  if (root.getAttribute("aria-busy") === null) {
+    const current = normalize(root.dataset.currentPath || location.pathname);
+    rehighlight(root, current);
+  } else {
+    void hydrateDocsNav();
+  }
+});