@dogsbay/docs-layout 0.2.0-beta.14 → 0.2.0-beta.140

package/src/DocsNavClient.astro

@@ -0,0 +1,113 @@
+---
+/**
+ * Client-rendered drop-in replacement for SidebarNavTree.
+ *
+ * Emits an empty placeholder with the metadata the hydration script
+ * needs (nav-url to fetch, current-path to highlight, basePath for
+ * version/locale filtering). The actual tree DOM is rendered by
+ * `docs-nav-client.ts` after a single fetch of `nav.json` (cached
+ * once per session — subsequent navigations re-highlight without
+ * re-fetching, courtesy of view transitions).
+ *
+ * The placeholder shows a few skeleton rows so the layout doesn't
+ * shift when the real tree pops in. Skeleton uses the same width as
+ * the sidebar so visual jump is minimal even on a slow connection.
+ *
+ * Trade-offs vs SidebarNavTree:
+ *   - HTML per page: ~200 bytes (this placeholder + a tiny script
+ *     tag) vs ~600 KB+ for the SSR tree at scale.
+ *   - No-JS users see only the skeleton + the `<noscript>` fallback
+ *     link. A `sitemap-index.xml` link covers no-JS navigation —
+ *     note `emitSitemapFiles` only runs when `site.url` is a valid
+ *     http(s) URL, so a site without one has no sitemap for this
+ *     fallback to reach.
+ *   - First paint waits for the JS bundle + the JSON fetch. On a 4G
+ *     connection that's typically <200 ms; the skeleton fills the
+ *     space until then.
+ *
+ * See plans/client-rendered-nav.md.
+ */
+interface Props {
+  /** Current page's URL pathname; the script uses it to mark the active item. */
+  currentPath: string;
+  /**
+   * URL prefix the host serves under (combined `urlBase` + `basePath`).
+   * The script joins this with `/_dogsbay/nav.json` to locate the
+   * fetchable nav tree; also threaded to the version/locale filter
+   * so multi-axis sites work the same as SSR.
+   */
+  basePath?: string;
+  /** Current source's product/namespace, if multi-product site. */
+  namespace?: string;
+  /** Current source's version axis value, if multi-version site. */
+  version?: string;
+  /** Current source's locale axis value, if multi-locale site. */
+  locale?: string;
+  /** The version served at the site root (`path: ""`), if any. */
+  rootVersion?: string;
+  /** The other versions' URL segments (left out of the root version's nav). */
+  versionSegments?: string[];
+}
+
+const { currentPath, basePath = "", namespace, version, locale, rootVersion, versionSegments } = Astro.props;
+const navUrl = `${basePath}/_dogsbay/nav.json`;
+---
+
+{/*
+  `role="navigation"` is REQUIRED here, not decoration: `aria-label` and
+  `aria-busy` are prohibited on a generic div (axe: aria-prohibited-attr,
+  serious) because a role-less element has no accessible name to label.
+  Giving the nav container its real role makes both attributes legal and
+  makes the landmark discoverable — it was previously neither.
+*/}
+<div
+  id="docs-nav-root"
+  role="navigation"
+  data-nav-url={navUrl}
+  data-current-path={currentPath}
+  data-base-path={basePath}
+  data-namespace={namespace ?? ""}
+  data-version={version ?? ""}
+  data-locale={locale ?? ""}
+  data-root-version={rootVersion ?? ""}
+  data-version-segments={(versionSegments ?? []).join(" ")}
+  aria-busy="true"
+  aria-label="Documentation navigation"
+>
+  <ul class="flex min-w-0 flex-col" data-sidebar="nav-tree" data-level="0">
+    {[0, 1, 2, 3, 4, 5].map((i) => (
+      <li>
+        <div
+          class="flex h-8 w-full items-center gap-2 rounded-md px-2"
+          aria-hidden="true"
+        >
+          <div class="h-2 w-2 rounded-full bg-sidebar-foreground/10" />
+          <div
+            class="h-2 rounded bg-sidebar-foreground/10"
+            style={`width: ${50 + ((i * 17) % 35)}%;`}
+          />
+        </div>
+      </li>
+    ))}
+  </ul>
+  <noscript>
+    <p class="px-2 py-1.5 text-sm text-sidebar-foreground/70">
+      JavaScript is required to render the sidebar. Use the
+      {/* sitemap-index.xml, not sitemap.xml — Dogsbay emits the
+          sitemap-index / sitemap-0 pair directly (see emitSitemapFiles);
+          `sitemap.xml` has never existed, so this no-JS fallback link
+          404'd on every site. */}
+      <a href={`${basePath}/sitemap-index.xml`} class="underline">sitemap</a>
+      to browse all pages.
+    </p>
+  </noscript>
+</div>
+
+<script>
+  // Single import — Astro/Vite bundles this into one shared chunk
+  // referenced from every page that uses DocsNavClient. Browsers
+  // cache the chunk, so the nav script ships once per session
+  // regardless of how many pages the user visits.
+  import { hydrateDocsNav } from "./docs-nav-client.ts";
+  hydrateDocsNav();
+</script>

package/src/DocsToc.astro

@@ -33,7 +33,7 @@ const filtered = headings.filter(h => h.depth >= minDepth && h.depth <= maxDepth
 
 {filtered.length > 0 && (
   <nav class:list={["text-sm", className]} aria-label="Table of contents">
-    <div class="text-xs font-semibold uppercase text-muted-foreground">{title}</div>
+    {title && <div class="text-xs font-semibold uppercase text-muted-foreground">{title}</div>}
     <ul class="mt-2 space-y-1">
       {filtered.map(h => (
         <li>

package/src/SearchDialog.astro

@@ -28,10 +28,35 @@ 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;
+  /**
+   * The base Pagefind prefixes result URLs with. Pagefind's own default is
+   * the folder above the bundle, which is right for GitHub Pages project
+   * sites and doubles the prefix on Workers subpath mounts (their index
+   * already carries the mount). format-astro computes the right value per
+   * layout; when absent, Pagefind's default is left alone. See
+   * `pagefind-base-url.ts`.
+   */
+  pagefindBaseUrl?: 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;
   /**
@@ -41,19 +66,35 @@ interface Props {
    * back to slugs when undefined.
    */
   taxonomyDisplay?: Record<string, TaxonomyDisplay>;
+  /**
+   * Current page's product (namespace) and version. On a multi-product /
+   * versioned site, search opens PRE-SCOPED to these — a Calico 3.32 page
+   * searches Calico 3.32 by default. The scope is seeded as normal facet
+   * selections, so the reader can untick them to search wider.
+   */
+  scopeProduct?: string;
+  scopeVersion?: string;
 }
 
 const {
-  pagefindUrl = "/pagefind/",
+  pagefindUrl,
+  pagefindBaseUrl,
+  navUrl,
   placeholder = "Search docs...",
   taxonomyDisplay,
+  scopeProduct,
+  scopeVersion,
 } = Astro.props;
 ---
 
 <dialog
   data-search-dialog
   data-pagefind-url={pagefindUrl}
+  data-pagefind-base-url={pagefindBaseUrl}
+  data-nav-url={navUrl}
   data-taxonomy-display={taxonomyDisplay ? JSON.stringify(taxonomyDisplay) : ""}
+  data-scope-product={scopeProduct ?? ""}
+  data-scope-version={scopeVersion ?? ""}
   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"
 >
   <form method="dialog" class="flex flex-col">
@@ -156,15 +197,22 @@ 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";
+  import { applyPagefindBaseUrl } from "./pagefind-base-url.js";
 
   type PagefindResult = {
     id: string;
@@ -177,15 +225,24 @@ 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>>>;
+    options?(opts: { baseUrl?: string }): Promise<void>;
   };
 
   const dialog = document.querySelector<HTMLDialogElement>("[data-search-dialog]");
+  // Current page's product/version — search opens pre-scoped to these.
+  const scopeProduct = dialog?.dataset.scopeProduct || "";
+  const scopeVersion = dialog?.dataset.scopeVersion || "";
   const trigger = document.querySelector<HTMLButtonElement>("[data-search-trigger]");
   const input = dialog?.querySelector<HTMLInputElement>("[data-search-input]");
   const resultsBox = dialog?.querySelector<HTMLDivElement>("[data-search-results]");
@@ -204,6 +261,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,10 +284,28 @@ 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;
+          // Before the first search: result URLs are built with this base.
+          // Without it a Workers subpath mount links to /<mount>/<mount>/page/.
+          await applyPagefindBaseUrl(mod, dialog!.dataset.pagefindBaseUrl);
           pagefind = mod;
           // Discover facets once, on first load. Pagefind builds
           // this from the body-level data-pagefind-filter elements.
@@ -237,6 +321,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 +440,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 +615,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) {
@@ -425,9 +683,22 @@ const {
       const fromUrl = parseFiltersFromUrl(new URLSearchParams(window.location.search));
       input!.value = fromUrl.query;
       filters = fromUrl.filters;
+      const hadUrlState = fromUrl.query.length > 0 || countActiveFilters(filters) > 0;
+      // Auto-scope: a FRESH open (no filters/query carried in the URL) on a
+      // multi-product/versioned site starts scoped to the CURRENT product +
+      // version. Seeded as ordinary facet selections, so the reader can
+      // untick "Product: calico" / "Version: 3.32" to search wider. A URL
+      // that already carries state wins (shared/roundtripped searches).
+      if (!hadUrlState) {
+        if (scopeProduct) filters.product = [scopeProduct];
+        if (scopeVersion) filters.version = [scopeVersion];
+      }
       renderFacets();
 
-      const hasInitial = input!.value.length > 0 || countActiveFilters(filters) > 0;
+      // Run immediately only when there's a query or the state came from the
+      // URL. A fresh open shows the empty prompt with the scope pre-ticked —
+      // results appear (scoped) as soon as the reader types.
+      const hasInitial = hadUrlState;
       if (hasInitial) {
         runSearch(input!.value);
       } else {
@@ -475,13 +746,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/TagList.astro

@@ -48,6 +48,11 @@ interface Props {
    * text. URL still uses the slug.
    */
   labels?: Record<string, string>;
+  /**
+   * Give chips whose prefix has no color a stable palette color,
+   * hashed from the tag's first segment. Default false.
+   */
+  autoColor?: boolean;
   /** Optional aria-label override; default "Tags". */
   label?: string;
   class?: string;
@@ -58,11 +63,12 @@ const {
   indexPath = "/tags",
   prefixes,
   labels,
+  autoColor = false,
   label: ariaLabel = "Tags",
   class: className,
 } = Astro.props;
 
-const chips = buildChips(tags, { indexPath, prefixes, labels });
+const chips = buildChips(tags, { indexPath, prefixes, labels, autoColor });
 
 /**
  * Closed palette → Tailwind class strings. Each entry is one
@@ -72,8 +78,13 @@ const chips = buildChips(tags, { indexPath, prefixes, labels });
  */
 const PALETTE: Record<TagPaletteName, string> = {
   blue: "border-blue-500/40 bg-blue-500/15 text-blue-700 dark:text-blue-300",
+  // amber-800, not -700, in light mode: amber-700 on amber-500/15 is
+  // 4.48:1 — under 4.5:1 by a hair, and failing regardless of the
+  // opacity bug below. -800 gives 6.32:1. Every other colour clears it
+  // at -700 (4.76–8.60:1). Dark mode is unaffected: text-*-300 on the
+  // same tint over a dark page is 9–12:1 across the palette.
   amber:
-    "border-amber-500/40 bg-amber-500/15 text-amber-700 dark:text-amber-300",
+    "border-amber-500/40 bg-amber-500/15 text-amber-800 dark:text-amber-300",
   emerald:
     "border-emerald-500/40 bg-emerald-500/15 text-emerald-700 dark:text-emerald-300",
   violet:
@@ -108,7 +119,17 @@ const DEFAULT_CLASS =
         >
           {chip.prefixLabel ? (
             <Fragment>
-              <span class="opacity-70">{chip.prefixLabel}:</span>
+              {/*
+                No opacity here. `opacity-70` on the prefix blended the
+                text 30% toward the chip background and put EVERY colour
+                in the palette below 4.5:1 — measured 2.75–3.95:1, worst
+                amber, best slate. It is 12px text, so 4.5:1 applies.
+
+                The prefix/leaf distinction is carried by font-weight
+                instead: the leaf below is font-semibold against the
+                anchor's font-medium. Weight costs no contrast.
+              */}
+              <span>{chip.prefixLabel}:</span>
               <span class="font-semibold">{chip.leafLabel}</span>
             </Fragment>
           ) : (