@dogsbay/docs-layout 0.2.0-beta.71 → 0.2.0-beta.73

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dogsbay/docs-layout",
-  "version": "0.2.0-beta.71",
+  "version": "0.2.0-beta.73",
   "description": "Standard documentation layout components for Dogsbay",
   "type": "module",
   "exports": {
@@ -29,8 +29,8 @@
     "./json-ld": "./src/json-ld.ts"
   },
   "dependencies": {
-    "@dogsbay/ui": "0.2.0-beta.71",
-    "@dogsbay/primitives": "0.2.0-beta.71"
+    "@dogsbay/ui": "0.2.0-beta.73",
+    "@dogsbay/primitives": "0.2.0-beta.73"
   },
   "devDependencies": {
     "vitest": "^3.0.0"

package/src/DocsLayout.astro

@@ -792,6 +792,7 @@ const siteIcon = '<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16"
             {!hideSearch && (
               <SearchDialog
                 pagefindUrl={pagefindUrl}
+                navUrl={basePath ? `${basePath}/_dogsbay/nav.json` : "/_dogsbay/nav.json"}
                 taxonomyDisplay={taxonomyDisplay}
               />
             )}

package/src/SearchDialog.astro

@@ -37,6 +37,17 @@ interface Props {
    * 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;
   /**
@@ -50,6 +61,7 @@ interface Props {
 
 const {
   pagefindUrl,
+  navUrl,
   placeholder = "Search docs...",
   taxonomyDisplay,
 } = Astro.props;
@@ -58,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"
 >
@@ -161,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";
 
@@ -182,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>>>;
   };
@@ -209,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 = (() => {
@@ -257,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;")
@@ -333,54 +409,170 @@ 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) {
+            // Slash-encoded values build a tree directly from their
+            // values; segment-encoded values need nav.json for
+            // structure. The helper detects which and falls back to
+            // a flat list when segment-encoded + no nav yet — phase 3
+            // upgrades to the real tree as soon as ensureNavLoaded
+            // resolves and re-renders.
+            const segmentEncoded = !entries.some((e) =>
+              e.value.includes("/"),
+            );
+            if (segmentEncoded && 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>
@@ -391,6 +583,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) {
@@ -495,13 +701,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/search-facets.ts

@@ -16,6 +16,33 @@ import type { PrefixDisplay } from "./tag-list-data.js";
 export interface TaxonomyDisplay {
   prefixes?: Record<string, PrefixDisplay>;
   labels?: Record<string, string>;
+  /**
+   * Sort weight for the facet column in the search dialog. Lower
+   * numbers appear first. Facets without an `order` sort
+   * alphabetically *after* any pinned ones — so `{ type: { order: 1 } }`
+   * promotes "Type" to the top while everything else stays alpha.
+   */
+  order?: number;
+  /**
+   * Render this facet as a tree instead of a flat checkbox list.
+   * See `buildFacetTree` for the two derivation strategies (slash-
+   * encoded vs nav-driven segment-encoded) and the canonical
+   * @dogsbay/types definition for full semantics.
+   */
+  hierarchical?: boolean;
+}
+
+/**
+ * Minimal nav item shape — mirrors `@dogsbay/types`' `NavItem`
+ * locally so this module has no runtime dependency on the types
+ * package. Used as input to `buildFacetTree` for segment-encoded
+ * facets (the auto-`category` case), where the document tree is
+ * the source of structure and order.
+ */
+export interface NavLike {
+  label: string;
+  href?: string;
+  children?: NavLike[];
 }
 
 /** Map of taxonomy name → display config. */
@@ -120,6 +147,40 @@ export function resolveFacetTitle(facetName: string): string {
     .replace(/\b\w/g, (c) => c.toUpperCase());
 }
 
+/**
+ * Return facet names in sidebar render order.
+ *
+ * Pagefind's `filters()` map iterates in index-discovery order
+ * (effectively the first page Pagefind happened to read), so without
+ * sorting the column order is arbitrary and shifts between builds.
+ * Order rule:
+ *  1. Facets with a numeric `order` in their `TaxonomyDisplay`
+ *     come first, ascending — use this to pin "Type" or "Audience"
+ *     to the top regardless of name.
+ *  2. Everything else sorts alphabetically by facet name.
+ * Stable within each tier so ties don't shuffle.
+ */
+export function sortFacetNames(
+  names: string[],
+  display?: TaxonomyDisplayMap,
+): string[] {
+  const withOrder = (name: string): number | undefined => {
+    const o = display?.[name]?.order;
+    return typeof o === "number" ? o : undefined;
+  };
+  return [...names].sort((a, b) => {
+    const oa = withOrder(a);
+    const ob = withOrder(b);
+    if (oa !== undefined && ob !== undefined) {
+      if (oa !== ob) return oa - ob;
+      return a.localeCompare(b);
+    }
+    if (oa !== undefined) return -1;
+    if (ob !== undefined) return 1;
+    return a.localeCompare(b);
+  });
+}
+
 // ── URL persistence ──────────────────────────────────────────────
 
 /**
@@ -175,21 +236,32 @@ export function parseFiltersFromUrl(
 }
 
 /**
- * Pagefind's `search()` accepts filters keyed by facet name with
- * either a single value, an array (OR), or a nested operator
- * object. We always pass the array form so multi-select works
- * within a facet without special-casing single-select.
+ * Build Pagefind's `filters` argument from internal facet state.
+ *
+ * Pagefind's array shape (`{ tag: ["a", "b"] }`) is AND by default —
+ * "page must have BOTH tags" — per
+ * https://pagefind.app/docs/js-api-filtering/ ("All filtering
+ * defaults to AND filtering"). That's the wrong UX for faceted
+ * search: clicking two checkboxes in the same group should widen
+ * the result set, not collapse it to zero. We wrap each facet in
+ * `{ any: [...] }` so multi-select within a facet is OR. Across
+ * different facets Pagefind already ANDs the keys, which matches
+ * the standard "narrow with each additional dimension" UX.
+ *
+ * Single-value selections also go through `{ any: ["x"] }` —
+ * Pagefind treats a one-element `any` identically to a bare string,
+ * so there's no behavioural delta and the code stays branch-free.
  *
  * Empty filter state → `{}` (Pagefind returns the unfiltered
- * result set). A facet with an empty array also drops out so we
- * don't accidentally narrow to "must equal nothing".
+ * result set). A facet with an empty array drops out so we don't
+ * accidentally narrow to "must equal nothing".
  */
 export function filterStateToPagefindFilters(
   filters: FilterState,
-): Record<string, string[]> {
-  const out: Record<string, string[]> = {};
+): Record<string, { any: string[] }> {
+  const out: Record<string, { any: string[] }> = {};
   for (const [name, values] of Object.entries(filters)) {
-    if (values.length > 0) out[name] = [...values];
+    if (values.length > 0) out[name] = { any: [...values] };
   }
   return out;
 }
@@ -230,3 +302,355 @@ export function countActiveFilters(filters: FilterState): number {
   for (const values of Object.values(filters)) n += values.length;
   return n;
 }
+
+// ── Hierarchical facets ──────────────────────────────────────────
+
+/**
+ * One node in a hierarchical facet tree (see `buildFacetTree`).
+ *
+ * `value` is the canonical Pagefind filter value for this node —
+ * for slash-encoded facets the full slash-joined path
+ * (`concept/a11y`); for segment-encoded facets a single segment
+ * (`installing_aws`). `value` matches Pagefind's value key 1:1
+ * for "real" entries; synthetic parents (intermediate trie nodes
+ * that don't correspond to a Pagefind entry) reuse the same
+ * derived value but carry `hasValue: false` and `count: 0`.
+ */
+export interface FacetTreeNode {
+  value: string;
+  label: string;
+  count: number;
+  depth: number;
+  /** True if Pagefind reported this exact value; false for synthetic parents. */
+  hasValue: boolean;
+  children: FacetTreeNode[];
+}
+
+/**
+ * Build a hierarchical facet tree from Pagefind's flat entry list.
+ *
+ * Two strategies depending on the values' shape:
+ *
+ *  - **Slash-encoded.** When at least one entry value contains `/`,
+ *    each value is treated as a path through the tree (`concept/a11y`
+ *    →  `concept → a11y`). Splits on `/`, inserts into a trie.
+ *    Parent entries that don't have a Pagefind value of their own
+ *    (e.g. `concept` standalone is unindexed but `concept/a11y` is)
+ *    appear as synthetic intermediate nodes with `hasValue: false`.
+ *    Within a parent, children sort by count desc then alpha — the
+ *    same rule as flat facets.
+ *
+ *  - **Segment-encoded.** When NO entry contains `/`, each value is
+ *    a single path segment. Hierarchy comes from `nav` — every nav
+ *    leaf's href segments become a chain in the trie. Counts come
+ *    from Pagefind's entry list, attached to nodes whose segment
+ *    name matches an entry value. **Caveat:** Pagefind reports one
+ *    count per distinct segment name regardless of where in the
+ *    tree it lives, so a segment that appears at multiple positions
+ *    (`installing/.../ipi`, `installing_azure/.../ipi`) gets the
+ *    same total count at every position — clicking selects the
+ *    shared value, returning pages from every position. This
+ *    matches the underlying Pagefind filter behaviour and is
+ *    documented in plans/hierarchical-facets.md.
+ *
+ *    Order is nav-document order, NOT count desc. Pagefind entries
+ *    not represented in nav are appended as orphans at the root in
+ *    alpha order.
+ *
+ *    When `nav` is undefined for the segment-encoded case, falls
+ *    back to a flat list (every entry a root-level node with no
+ *    children, in count-desc order) — preserves render-ability
+ *    when nav.json hasn't loaded yet.
+ *
+ * Returns the top-level nodes. Empty `entries` → empty array.
+ */
+export function buildFacetTree(
+  facetName: string,
+  entries: FacetEntry[],
+  options: {
+    nav?: NavLike[];
+    display?: TaxonomyDisplayMap;
+  } = {},
+): FacetTreeNode[] {
+  if (entries.length === 0) return [];
+
+  const slashEncoded = entries.some((e) => e.value.includes("/"));
+  if (slashEncoded) {
+    return buildSlashTree(facetName, entries, options.display);
+  }
+  return buildSegmentTree(facetName, entries, options.nav, options.display);
+}
+
+/**
+ * Slash-encoded tree builder. Each entry value is a slash-joined
+ * path; split, walk a trie, attach Pagefind counts to terminal
+ * nodes. Synthetic intermediate nodes (a path component used by a
+ * descendant but absent from `entries`) get `hasValue: false` and
+ * `count: 0` so they render but don't contribute to selection.
+ */
+function buildSlashTree(
+  facetName: string,
+  entries: FacetEntry[],
+  display?: TaxonomyDisplayMap,
+): FacetTreeNode[] {
+  // Trie keyed by full slash-path. Children are tracked on each
+  // node's own `children` array (built unsorted in pass 1, sorted
+  // recursively in pass 2).
+  const byPath = new Map<string, FacetTreeNode>();
+  const rootValues: string[] = [];
+
+  for (const entry of entries) {
+    const segments = entry.value.split("/").filter((s) => s.length > 0);
+    if (segments.length === 0) continue;
+    let pathSoFar = "";
+    let parent: FacetTreeNode | null = null;
+    for (let i = 0; i < segments.length; i++) {
+      pathSoFar = pathSoFar ? `${pathSoFar}/${segments[i]}` : segments[i];
+      let node = byPath.get(pathSoFar);
+      if (!node) {
+        node = {
+          value: pathSoFar,
+          label: resolveFacetLabel(facetName, pathSoFar, display),
+          count: 0,
+          depth: i,
+          hasValue: false,
+          children: [],
+        };
+        byPath.set(pathSoFar, node);
+        if (parent) parent.children.push(node);
+        else rootValues.push(pathSoFar);
+      }
+      if (i === segments.length - 1) {
+        node.count = entry.count;
+        node.hasValue = true;
+      }
+      parent = node;
+    }
+  }
+
+  // Pass 2: sort children at every depth. Mirrors sortFacetEntries
+  // (count desc, alpha tiebreaker).
+  const sortChildren = (node: FacetTreeNode): void => {
+    if (node.children.length === 0) return;
+    node.children.sort((a, b) => {
+      if (a.count !== b.count) return b.count - a.count;
+      return a.value.localeCompare(b.value);
+    });
+    for (const c of node.children) sortChildren(c);
+  };
+
+  const rootList = rootValues.map((v) => byPath.get(v)!);
+  rootList.sort((a, b) => {
+    if (a.count !== b.count) return b.count - a.count;
+    return a.value.localeCompare(b.value);
+  });
+  for (const r of rootList) sortChildren(r);
+  return rootList;
+}
+
+/**
+ * Segment-encoded tree builder. Walks `nav` to discover the
+ * canonical document hierarchy, then attaches Pagefind counts to
+ * any node whose segment name matches an entry. Pagefind entries
+ * not in nav are appended as alpha-sorted root orphans so they
+ * don't disappear.
+ */
+function buildSegmentTree(
+  facetName: string,
+  entries: FacetEntry[],
+  nav: NavLike[] | undefined,
+  display?: TaxonomyDisplayMap,
+): FacetTreeNode[] {
+  const byValue = new Map<string, FacetEntry>();
+  for (const e of entries) byValue.set(e.value, e);
+
+  if (!nav || nav.length === 0) {
+    // Flat fallback in count-desc order — preserves render-ability
+    // when nav hasn't loaded.
+    return entries.map((e) => ({
+      value: e.value,
+      label: resolveFacetLabel(facetName, e.value, display),
+      count: e.count,
+      depth: 0,
+      hasValue: true,
+      children: [],
+    }));
+  }
+
+  const seenValues = new Set<string>();
+  const roots: FacetTreeNode[] = [];
+  const rootIndex = new Map<string, FacetTreeNode>();
+
+  /** Insert a path's parent segments (excluding the leaf filename) into the trie. */
+  const insertPath = (segments: string[]): void => {
+    if (segments.length === 0) return;
+    let parentList: FacetTreeNode[] = roots;
+    let parentIndex: Map<string, FacetTreeNode> = rootIndex;
+    for (let i = 0; i < segments.length; i++) {
+      const seg = segments[i];
+      let node = parentIndex.get(seg);
+      if (!node) {
+        const entry = byValue.get(seg);
+        node = {
+          value: seg,
+          label: resolveFacetLabel(facetName, seg, display),
+          count: entry ? entry.count : 0,
+          depth: i,
+          hasValue: entry !== undefined,
+          children: [],
+        };
+        parentList.push(node);
+        parentIndex.set(seg, node);
+        if (entry) seenValues.add(seg);
+      }
+      // Walk into the child list for the next iteration. Each
+      // node carries its own child index lazily via a WeakMap-like
+      // closure; here we use a regular Map keyed off the node.
+      let nextIndex = childIndex.get(node);
+      if (!nextIndex) {
+        nextIndex = new Map();
+        childIndex.set(node, nextIndex);
+      }
+      parentList = node.children;
+      parentIndex = nextIndex;
+    }
+  };
+
+  const childIndex = new Map<FacetTreeNode, Map<string, FacetTreeNode>>();
+
+  // Walk every nav leaf. Use href segments (excluding the leaf
+  // filename) — those are the auto-derived `category` values
+  // emitted by parseMeta's deriveCategoryFromSlug.
+  const walkNav = (items: NavLike[]): void => {
+    for (const item of items) {
+      if (item.href) {
+        const parents = hrefToCategorySegments(item.href);
+        insertPath(parents);
+      }
+      if (item.children && item.children.length > 0) walkNav(item.children);
+    }
+  };
+  walkNav(nav);
+
+  // Pagefind values not represented in nav → root-level orphans in
+  // alpha order. Without this they vanish from the UI silently.
+  const orphans: FacetTreeNode[] = [];
+  for (const e of entries) {
+    if (seenValues.has(e.value)) continue;
+    orphans.push({
+      value: e.value,
+      label: resolveFacetLabel(facetName, e.value, display),
+      count: e.count,
+      depth: 0,
+      hasValue: true,
+      children: [],
+    });
+  }
+  orphans.sort((a, b) => a.value.localeCompare(b.value));
+  return [...roots, ...orphans];
+}
+
+/**
+ * Strip an href down to its parent path segments — the `category`
+ * derivation logic from `parseMeta.deriveCategoryFromSlug`. Drops
+ * leading/trailing slashes, drops the leaf filename segment.
+ */
+function hrefToCategorySegments(href: string): string[] {
+  // Drop scheme/host if absolute (we only treat path segments)
+  let path = href;
+  try {
+    if (/^[a-z]+:\/\//i.test(href)) path = new URL(href).pathname;
+  } catch {
+    // not a URL — treat as-is
+  }
+  // Drop hash + query — facets care about the URL path only
+  path = path.split("#")[0].split("?")[0];
+  const segments = path.split("/").filter((s) => s.length > 0);
+  // Match deriveCategoryFromSlug: parents = everything except the leaf
+  if (segments.length < 2) return [];
+  return segments.slice(0, -1);
+}
+
+/**
+ * Flat list of every "real" Pagefind value at or under `node`
+ * (i.e. every node where `hasValue === true`). Synthetic parents
+ * are excluded since adding them to the filter would be a no-op
+ * (Pagefind has no pages tagged with the synthetic value).
+ *
+ * Used by `toggleTreeNode` when the user ticks a parent — we add
+ * every real descendant value to the selection in one shot.
+ */
+export function collectDescendantValues(node: FacetTreeNode): string[] {
+  const out: string[] = [];
+  const visit = (n: FacetTreeNode): void => {
+    if (n.hasValue) out.push(n.value);
+    for (const c of n.children) visit(c);
+  };
+  visit(node);
+  return out;
+}
+
+/**
+ * Tri-state of a tree node given the current filter state.
+ *
+ *  - `"checked"`     — every real descendant value (and self if
+ *                       self has a value) is in `filters[facetName]`.
+ *  - `"unchecked"`    — none of them are.
+ *  - `"indeterminate"`— at least one is, but not all.
+ *
+ * Synthetic parents with no real-value descendants resolve to
+ * "unchecked" (defensive default — shouldn't occur in valid trees).
+ */
+export function computeTreeState(
+  node: FacetTreeNode,
+  facetName: string,
+  filters: FilterState,
+): "checked" | "unchecked" | "indeterminate" {
+  const descendants = collectDescendantValues(node);
+  if (descendants.length === 0) return "unchecked";
+  const selected = new Set(filters[facetName] ?? []);
+  let hits = 0;
+  for (const v of descendants) if (selected.has(v)) hits++;
+  if (hits === 0) return "unchecked";
+  if (hits === descendants.length) return "checked";
+  return "indeterminate";
+}
+
+/**
+ * Toggle a tree node's selection.
+ *
+ *  - If currently checked → remove self + all descendant values
+ *    from `filters[facetName]`.
+ *  - If unchecked or indeterminate → add self + all descendant
+ *    values (auto-select). Matches the decided UX: parent click
+ *    fans out to children.
+ *
+ * Returns a new `FilterState` — input is not mutated. Same
+ * immutability contract as `toggleFilter`.
+ */
+export function toggleTreeNode(
+  filters: FilterState,
+  facetName: string,
+  node: FacetTreeNode,
+  currentState: "checked" | "unchecked" | "indeterminate",
+): FilterState {
+  const descendants = collectDescendantValues(node);
+  if (descendants.length === 0) return filters;
+  const current = filters[facetName] ?? [];
+  let nextValues: string[];
+  if (currentState === "checked") {
+    const drop = new Set(descendants);
+    nextValues = current.filter((v) => !drop.has(v));
+  } else {
+    const merged = new Set(current);
+    for (const v of descendants) merged.add(v);
+    nextValues = Array.from(merged);
+  }
+  const next: FilterState = { ...filters };
+  if (nextValues.length === 0) {
+    delete next[facetName];
+  } else {
+    next[facetName] = nextValues;
+  }
+  return next;
+}