@leed-ai/cli 0.0.0 → 6.19.0

package/dist/static/javascript/live-search.js

@@ -0,0 +1,986 @@
+/**
+ * Live documentation search (#329) — the Starter+ replacement for lunr-search.js.
+ *
+ * Instead of downloading a prebuilt Lunr index, this queries `/api/search` on the
+ * site's own origin (same-origin, no CORS). Typing runs cheap `mode=freetext`
+ * requests; pressing Enter runs one `mode=hybrid` request, the only path that
+ * spends a semantic embedding.
+ *
+ * Shipped as a plain classic script (no bundler), so it is one self-contained
+ * file like the lunr client it replaces. Its whole UI layer — the modal
+ * anchoring, Alpine `headerSearchShow` contract, capture-phase Ctrl+K handler,
+ * arrow-key selection and localStorage recent searches — is preserved verbatim
+ * from that file so both header variants and any custom `docs-header.hbs` keep
+ * working. Only the data layer changed.
+ *
+ * The page emits only `pt` (this page's page type id). The SEARCH INDEX is a
+ * build-time concern of the prebuilt Lunr index and nothing else — live search
+ * never sees it. The searchable universe is resolved server-side from `pt`, and
+ * the filter chips come from `/api/search/facets`, browser-cached, so an index
+ * edited in the CMS is picked up without a republish.
+ */
+
+const SEARCH_ENDPOINT = "/api/search";
+/** Filter chips for the modal. Cache-Control'd by the origin; fetched once per open. */
+const FACETS_ENDPOINT = "/api/search/facets";
+/** Below this many characters, typing shows recent searches instead of querying. */
+const MIN_QUERY_LENGTH = 3;
+/** Debounce for the freetext-while-typing path. */
+const SEARCH_DEBOUNCE_MS = 300;
+
+/** Page types of the reader's search index, from `/api/search/facets`. */
+let searchFacets = [];
+/** Set once the facets request has resolved, so the modal fetches them only once. */
+let facetsLoaded = false;
+/**
+ * Set when the server says this page type has no usable search index. That is a
+ * PERMANENT configuration state, not an outage, so the modal stops querying
+ * instead of showing a "temporarily unavailable" box on every keystroke.
+ */
+let searchUnconfigured = false;
+/** The active filter chip's page type id, or null for the whole index. */
+let activeFilter = null;
+/**
+ * The page type of the page being read, emitted by `head.hbs`. This is the ONLY
+ * search-related value the page carries — everything else is resolved by the
+ * server. Read defensively once: a bare reference would throw a ReferenceError
+ * and kill search outright if the constant were ever absent.
+ */
+const currentPageTypeId = typeof pt === "string" ? pt : "";
+
+/**
+ * Confirm the page can host live search. Mirrors `initializeSearch`'s guard
+ * order in lunr-search.js: the MODAL is the anchor, not the trigger button — the
+ * docs shell always renders the modal, while the button lives in the header,
+ * which a site can replace via `_includes/docs-header.hbs`.
+ */
+function initializeSearch() {
+  // Silent: a non-docs page legitimately has no modal, and that is not an error.
+  //
+  // No console.log/debug/info anywhere in this file. The rolldown log-stripping
+  // (`manualPureFunctions`, CI-only) covers ONLY the bundled trackers built from
+  // src/trackers/*.ts; a hand-written script under static/javascript is copied
+  // verbatim to the customer site (rollup-plugin-copy, then fs.copyFile), and the
+  // `.min.js` in the versioned filename is naming, not minification. So anything
+  // logged here prints in every reader's console. console.warn/error stay — the
+  // tracker configs deliberately leave those two in production too.
+  //
+  // Availability is NOT decided here. The server is the only authority on whether
+  // this page type has a usable search index, and it answers on the first request
+  // — so a site whose index is configured (or removed) takes effect immediately,
+  // with no republish and nothing baked into the page to go stale.
+  return !!document.querySelector("#document-search-modal");
+}
+
+/**
+ * Load the filter chips for this page's search index, once per page view.
+ *
+ * Best-effort by design: chips are an affordance, not the feature. A failure
+ * here leaves `searchFacets` empty — the modal then simply offers no filters and
+ * searches the whole index, which is the default behavior anyway. Only a failing
+ * SEARCH is worth showing the reader an error for.
+ */
+async function loadFacets() {
+  if (facetsLoaded) return;
+  facetsLoaded = true;
+
+  try {
+    const response = await fetch(`${FACETS_ENDPOINT}?pageTypeId=${encodeURIComponent(currentPageTypeId)}`);
+    if (!response.ok) return;
+    const body = await response.json();
+    if (Array.isArray(body.facets)) {
+      searchFacets = body.facets;
+    }
+  } catch {
+    // Offline, blocked, or the endpoint is down — searching still works.
+  }
+}
+
+/** Escape text before it is interpolated into result markup. */
+function escapeHtml(value) {
+  return String(value ?? "")
+    .replace(/&/g, "&")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;");
+}
+
+/**
+ * Query the live endpoint. Resolves to the parsed body, or throws so the caller
+ * can render the explicit unavailable state — a failed search must never look
+ * like an empty result set.
+ *
+ * The chips are baked in at publish time, so an index edited since the last
+ * publish can leave a chip the server no longer accepts: it rejects the filter
+ * with `400 invalid_filter` rather than quietly widening the search. That is the
+ * intended strictness, so the client recovers instead — it drops the filter and
+ * retries once, and the retry's authoritative `facets` remove the dead chip.
+ */
+async function requestSearch(query, mode, signal) {
+  const send = () => {
+    const params = new URLSearchParams({ q: query, pageTypeId: currentPageTypeId, mode });
+    if (activeFilter) {
+      params.append("pageTypeIds", activeFilter);
+    }
+    return fetch(`${SEARCH_ENDPOINT}?${params.toString()}`, { signal });
+  };
+
+  let response = await send();
+  if (response.status === 400 && activeFilter && (await isStaleFilter(response))) {
+    activeFilter = null;
+    response = await send();
+  }
+  // `invalid_page_type` is permanent: this page type is not a docs type, or has
+  // no search index configured. Retrying cannot fix it, and calling it
+  // "temporarily unavailable" on every keystroke is simply untrue. Latch it and
+  // fall silent — the same shape as a free-tier site with no index built.
+  if (response.status === 400 && (await isUnconfigured(response))) {
+    searchUnconfigured = true;
+    return null;
+  }
+  if (!response.ok) {
+    throw new Error(`Search request failed: ${response.status}`);
+  }
+  return response.json();
+}
+
+/**
+ * How long a search will wait for the tracker to establish a session before
+ * querying anyway. The identity is a nice-to-have on the log row; the search is
+ * the thing the reader asked for, so it must never be held hostage to it.
+ */
+const SESSION_WAIT_MS = 1500;
+
+/** Set once the first search has already waited — the session establishes once. */
+let sessionSettled = false;
+
+/**
+ * Give the tracker a chance to establish `__lid`/`__sid` before the first query.
+ *
+ * `whisper.js` mints the session with an ASYNC fingerprint round-trip, and the
+ * search endpoint only READS those cookies (it never mints a session of its own,
+ * by design — otherwise every debounced keystroke would write tracking rows). So
+ * a reader who opens search immediately on a cold visit would otherwise log
+ * queries with no `leadDetailsId`, and the query-to-reader attribution this
+ * feature exists to provide would silently be missing exactly where a reader's
+ * first search is the most interesting signal we have.
+ *
+ * `utilities.js` gates forms, recommendations and CTAs on the same global. This
+ * is deliberately best-effort: if the tracker is blocked, absent, or slow, the
+ * search proceeds anyway after SESSION_WAIT_MS and simply logs without the lead.
+ */
+async function awaitSessionReady() {
+  if (sessionSettled) return;
+  sessionSettled = true;
+
+  if (typeof window.leedSessionReady !== "function") return;
+
+  try {
+    await Promise.race([
+      // MUST be a SessionStartedEventName — the /api/lid body is validated
+      // against that enum, so an invented name ("docs_search") 400s and the
+      // session is never established. `utilities.js` passes "pageview" for its
+      // non-form triggers (recommendations, CTAs); search does the same.
+      window.leedSessionReady("pageview"),
+      new Promise((resolve) => setTimeout(resolve, SESSION_WAIT_MS)),
+    ]);
+  } catch {
+    // A tracker failure must never block search.
+  }
+}
+
+/** True when a 400 means this page type can never be searched, however often we ask. */
+async function isUnconfigured(response) {
+  try {
+    return (await response.clone().json()).error === "invalid_page_type";
+  } catch {
+    return false;
+  }
+}
+
+/** True when a 400 was caused by a filter the resolved index no longer contains. */
+async function isStaleFilter(response) {
+  try {
+    return (await response.json()).error === "invalid_filter";
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Search UI integration for existing modal
+ */
+class SearchUI {
+  constructor(options = {}) {
+    this.searchInput = null;
+    this.searchResults = null;
+    this.searchFilters = null;
+    this.renderedChips = null;
+    this.searchTimeout = null;
+    this.saveTimeout = null;
+    this.isInitialized = false;
+    this.pendingRequest = null;
+
+    // Selection tracking
+    this.selectedIndex = -1;
+    this.selectableItems = [];
+
+    // Search history configuration
+    this.maxHistoryItems = options.maxHistoryItems || 5;
+    this.historyStorageKey = options.historyStorageKey || "searchHistory";
+    this.searchHistory = this.loadSearchHistory();
+  }
+
+  /**
+   * Initialize search UI with existing modal elements
+   */
+  initialize() {
+    this.searchInput = document.querySelector('#document-search-modal input[type="text"]');
+    this.searchResults = document.querySelector("#document-search-modal .search-results-container");
+    this.searchFilters = document.querySelector("#document-search-modal .search-filter-chips");
+
+    if (!this.searchInput || !this.searchResults) {
+      console.warn("Search modal elements not found");
+      return false;
+    }
+
+    this.setupEventListeners();
+    this.renderFilters();
+    this.showRecentSearches();
+    this.setupModalOpenListener();
+
+    this.isInitialized = true;
+    return true;
+  }
+
+  /**
+   * Setup listener for when modal opens to clear input
+   */
+  setupModalOpenListener() {
+    const searchTriggers = document.querySelectorAll("#document-search, #document-search-container");
+    searchTriggers.forEach((trigger) => {
+      trigger.addEventListener("click", () => {
+        this.loadFilters();
+        setTimeout(() => {
+          if (this.searchInput) {
+            this.searchInput.value = "";
+            this.searchInput.focus();
+            this.showRecentSearches();
+          }
+        }, 100);
+      });
+    });
+  }
+
+  /**
+   * Setup event listeners for search functionality
+   */
+  setupEventListeners() {
+    this.searchInput.addEventListener("input", (e) => {
+      const query = e.target.value.trim();
+      this.handleSearchInput(query);
+    });
+
+    this.searchInput.addEventListener("keydown", (e) => {
+      if (e.key === "Enter") {
+        e.preventDefault();
+        this.handleEnterKey();
+      } else if (e.key === "ArrowDown") {
+        e.preventDefault();
+        this.navigateSelection(1);
+      } else if (e.key === "ArrowUp") {
+        e.preventDefault();
+        this.navigateSelection(-1);
+      } else if (e.key === "Escape") {
+        // Let Alpine.js handle the escape key
+        return;
+      }
+    });
+
+    this.searchResults.addEventListener("click", (e) => {
+      const resultItem = e.target.closest("[data-url]");
+      if (resultItem) {
+        const url = resultItem.getAttribute("data-url");
+        this.addToSearchHistory(this.searchInput.value.trim());
+        this.navigateToUrl(url);
+        return;
+      }
+
+      const historyItem = e.target.closest("[data-query]");
+      if (historyItem) {
+        const query = historyItem.getAttribute("data-query");
+        this.searchInput.value = query;
+        this.performSearch(query, "hybrid", true);
+      }
+    });
+
+    if (this.searchFilters) {
+      this.searchFilters.addEventListener("click", (e) => {
+        const chip = e.target.closest("[data-page-type-id]");
+        if (!chip) return;
+        const id = chip.getAttribute("data-page-type-id");
+        activeFilter = activeFilter === id ? null : id;
+        this.renderFilters();
+        // A keystroke's debounce may still be pending; letting it fire would
+        // abort this scoped query and replace it with the unscoped one.
+        clearTimeout(this.searchTimeout);
+        const query = this.searchInput.value.trim();
+        if (query.length >= MIN_QUERY_LENGTH) {
+          this.performSearch(query, "freetext", false);
+        }
+      });
+    }
+  }
+
+  /**
+   * Render the page-type filter chips, marking the active one. The chip for the
+   * page the reader is on is offered first so scoping to the current doc set is
+   * one click; the whole index remains the default.
+   */
+  /**
+   * Fetch the chips on first modal open rather than at page load: a reader who
+   * never searches costs nothing, and the response is browser-cached so opening
+   * search repeatedly costs nothing either.
+   */
+  loadFilters() {
+    loadFacets().then(() => this.renderFilters());
+  }
+
+  renderFilters() {
+    if (!this.searchFilters) return;
+    // A single-set index has nothing to filter by.
+    const chips =
+      searchFacets.length <= 1
+        ? ""
+        : searchFacets
+            .slice()
+            // Stable, so the remaining sets keep their published order.
+            .sort((a, b) => (a.id === currentPageTypeId ? -1 : 0) - (b.id === currentPageTypeId ? -1 : 0))
+            .map((facet) => {
+              const classes = ["search-filter-chip"];
+              if (facet.id === activeFilter) classes.push("is-active");
+              if (facet.id === currentPageTypeId) classes.push("is-current");
+              return `<button type="button" class="${classes.join(" ")}" data-page-type-id="${escapeHtml(facet.id)}">${escapeHtml(facet.name)}</button>`;
+            })
+            .join("");
+
+    // Every debounced response re-runs this; rewriting identical markup would
+    // churn the DOM ~3x/second while typing and drop focus from a chip.
+    if (chips !== this.renderedChips) {
+      this.searchFilters.innerHTML = chips;
+      this.renderedChips = chips;
+    }
+  }
+
+  /**
+   * Adopt the authoritative page types the server resolved. The chips come from
+   * `/api/search/facets`, which is browser-cached, so within that TTL an index
+   * edited in the CMS can still leave a chip for a page type that is gone. Every
+   * search response carries the real set, so adopting it here keeps the modal
+   * self-healing at no extra request. (Recovery from a request that USED such a
+   * chip happens earlier, in `requestSearch`'s 400 retry — a 200 always means the
+   * filter was valid.)
+   */
+  reconcileFacets(facets) {
+    if (!Array.isArray(facets)) return;
+    searchFacets = facets;
+    this.renderFilters();
+  }
+
+  /**
+   * Handle search input with debouncing. Typing only ever runs the cheap
+   * freetext query; the semantic path is reserved for a deliberate Enter.
+   */
+  handleSearchInput(query) {
+    clearTimeout(this.searchTimeout);
+    clearTimeout(this.saveTimeout);
+
+    this.searchTimeout = setTimeout(() => {
+      if (query.length >= MIN_QUERY_LENGTH) {
+        this.performSearch(query, "freetext", false);
+      } else {
+        this.showRecentSearches();
+      }
+    }, SEARCH_DEBOUNCE_MS);
+
+    if (query.length >= MIN_QUERY_LENGTH) {
+      this.saveTimeout = setTimeout(() => {
+        this.addToSearchHistory(query);
+      }, 2000);
+    }
+  }
+
+  /**
+   * Handle Enter key press. A highlighted result still navigates; otherwise
+   * Enter is the deliberate-search trigger and runs one hybrid query, rather
+   * than jumping to the first hit as the lunr client did.
+   */
+  handleEnterKey() {
+    // A debounced freetext query is almost always pending when Enter lands. If
+    // it fired afterwards it would abort the hybrid request and overwrite the
+    // deliberate semantic results — throwing away the one embedding we spent.
+    clearTimeout(this.searchTimeout);
+    clearTimeout(this.saveTimeout);
+
+    const query = this.searchInput.value.trim();
+
+    if (this.selectedIndex >= 0 && this.selectedIndex < this.selectableItems.length) {
+      const selectedItem = this.selectableItems[this.selectedIndex];
+      const url = selectedItem.getAttribute("data-url");
+      const historyQuery = selectedItem.getAttribute("data-query");
+
+      if (url) {
+        this.addToSearchHistory(query);
+        this.navigateToUrl(url);
+        return;
+      } else if (historyQuery && query.length < MIN_QUERY_LENGTH) {
+        // A recent-search row is only the reader's intent while they have not
+        // typed a searchable query. Recent searches stay on screen during the
+        // 300 ms debounce, still auto-selected — so without this length check,
+        // Enter right after typing runs the OLD search instead of the words just
+        // typed, and spends the embedding on them.
+        this.searchInput.value = historyQuery;
+        this.performSearch(historyQuery, "hybrid", true);
+        return;
+      }
+    }
+
+    if (query.length < MIN_QUERY_LENGTH) {
+      return;
+    }
+
+    this.addToSearchHistory(query);
+    this.performSearch(query, "hybrid", false);
+  }
+
+  /**
+   * Navigate selection with arrow keys
+   */
+  navigateSelection(direction) {
+    if (this.selectableItems.length === 0) {
+      return;
+    }
+
+    this.selectedIndex += direction;
+
+    if (this.selectedIndex < 0) {
+      this.selectedIndex = this.selectableItems.length - 1;
+    } else if (this.selectedIndex >= this.selectableItems.length) {
+      this.selectedIndex = 0;
+    }
+
+    this.updateSelection();
+  }
+
+  /**
+   * Update visual selection highlighting
+   */
+  updateSelection() {
+    this.selectableItems.forEach((item) => {
+      item.classList.remove("search-result-selected");
+    });
+
+    if (this.selectedIndex >= 0 && this.selectedIndex < this.selectableItems.length) {
+      const selectedItem = this.selectableItems[this.selectedIndex];
+      selectedItem.classList.add("search-result-selected");
+
+      selectedItem.scrollIntoView({
+        behavior: "smooth",
+        block: "nearest",
+        inline: "nearest",
+      });
+    }
+  }
+
+  /**
+   * Reset selection
+   */
+  resetSelection() {
+    this.selectedIndex = -1;
+    this.selectableItems = [];
+  }
+
+  /**
+   * Navigate to a URL, handling current page case by closing modal
+   */
+  navigateToUrl(url) {
+    const currentUrl = window.location.pathname + window.location.search + window.location.hash;
+
+    if (url === currentUrl || url === window.location.href) {
+      this.closeModal();
+    } else {
+      const currentPathAndQuery = window.location.pathname + window.location.search;
+      const targetPathAndQuery = url.split("#")[0];
+
+      if (currentPathAndQuery === targetPathAndQuery) {
+        window.location.href = url;
+        setTimeout(() => this.closeModal(), 100);
+      } else {
+        window.location.href = url;
+      }
+    }
+  }
+
+  /**
+   * Close the search modal
+   */
+  closeModal() {
+    const searchModal = document.getElementById("document-search-modal");
+    if (searchModal && window.Alpine) {
+      // Find the parent Alpine.js component that contains headerSearchShow
+      // The headerSearchShow variable is in the header component, not the modal
+      let currentElement = searchModal;
+      let alpineData = null;
+
+      while (currentElement && currentElement !== document.body) {
+        alpineData = Alpine.$data(currentElement);
+        if (alpineData && typeof alpineData.headerSearchShow !== "undefined") {
+          alpineData.headerSearchShow = false;
+          return;
+        }
+        currentElement = currentElement.parentElement;
+      }
+
+      if (!alpineData || typeof alpineData.headerSearchShow === "undefined") {
+        const allElements = document.querySelectorAll("[x-data]");
+        for (const element of allElements) {
+          const data = Alpine.$data(element);
+          if (data && typeof data.headerSearchShow !== "undefined") {
+            data.headerSearchShow = false;
+            return;
+          }
+        }
+      }
+    }
+  }
+
+  /**
+   * Run one query against the live endpoint and render it. Any in-flight request
+   * is aborted first, so a fast typist never sees an earlier response overwrite a
+   * later one.
+   */
+  async performSearch(query, mode, saveToHistory = false) {
+    // Permanently unconfigured: stop asking. Every further keystroke would buy
+    // the same 400.
+    if (searchUnconfigured) {
+      this.showRecentSearches();
+      return;
+    }
+
+    if (this.pendingRequest) {
+      this.pendingRequest.abort();
+    }
+    const controller = new AbortController();
+    this.pendingRequest = controller;
+
+    try {
+      // Only ever waits on the first query of a visit; a no-op thereafter.
+      await awaitSessionReady();
+      if (controller.signal.aborted) return;
+
+      const body = await requestSearch(query, mode, controller.signal);
+      // `null` means the endpoint reported a permanent misconfiguration and the
+      // latch is now set. Leave the panel as it was rather than asserting either
+      // "no results" or "temporarily unavailable" — neither is true.
+      if (body === null) {
+        this.showRecentSearches();
+        return;
+      }
+      this.reconcileFacets(body.facets);
+      // `note` explains a hybrid→freetext downgrade, so the reader knows why a
+      // deliberate search came back with keyword-only results.
+      this.displayResults(Array.isArray(body.results) ? body.results : [], query, body.note ?? "");
+      if (saveToHistory) {
+        this.addToSearchHistory(query);
+      }
+    } catch (error) {
+      // `signal.aborted` also covers an abort swallowed while reading a 400 body.
+      if (error.name === "AbortError" || controller.signal.aborted) return;
+      console.error("Search error:", error);
+      this.displayUnavailable();
+    } finally {
+      if (this.pendingRequest === controller) {
+        this.pendingRequest = null;
+      }
+    }
+  }
+
+  /**
+   * Load search history from localStorage
+   */
+  loadSearchHistory() {
+    try {
+      const history = localStorage.getItem(this.historyStorageKey);
+      return history ? JSON.parse(history) : [];
+    } catch (error) {
+      console.warn("Failed to load search history:", error);
+      return [];
+    }
+  }
+
+  /**
+   * Save search history to localStorage
+   */
+  saveSearchHistory() {
+    try {
+      localStorage.setItem(this.historyStorageKey, JSON.stringify(this.searchHistory));
+    } catch (error) {
+      console.warn("Failed to save search history:", error);
+    }
+  }
+
+  /**
+   * Add a search query to history
+   */
+  addToSearchHistory(query) {
+    if (!query || query.trim().length < MIN_QUERY_LENGTH) return;
+
+    const trimmedQuery = query.trim();
+
+    this.searchHistory = this.searchHistory.filter((item) => item.query !== trimmedQuery);
+
+    this.searchHistory.unshift({
+      query: trimmedQuery,
+      timestamp: Date.now(),
+    });
+
+    this.searchHistory = this.searchHistory.slice(0, this.maxHistoryItems);
+
+    this.saveSearchHistory();
+  }
+
+  /**
+   * Clear search history
+   */
+  clearSearchHistory() {
+    this.searchHistory = [];
+    this.saveSearchHistory();
+  }
+
+  /**
+   * The explicit "search is temporarily unavailable" state. A failed, rate-limited
+   * or disabled endpoint must never be shown as "no results" — that would read as
+   * a statement about the docs rather than about the service.
+   */
+  displayUnavailable() {
+    this.resetSelection();
+    this.searchResults.innerHTML = `
+      <div class="search-unavailable">
+        <div class="search-no-results-title">Search is temporarily unavailable</div>
+        <div class="search-no-results-subtitle">Please try again in a moment.</div>
+      </div>
+    `;
+  }
+
+  /**
+   * Display search results
+   */
+  displayResults(results, query, note = "") {
+    this.resetSelection();
+
+    if (results.length === 0) {
+      // A downgraded search that found nothing still has to say so: otherwise an
+      // empty freetext fallback reads as a statement about the docs rather than
+      // about the weaker query the reader actually got.
+      this.searchResults.innerHTML = `
+        <div class="search-no-results">
+          <div class="search-no-results-title">No results found for "${escapeHtml(query)}"</div>
+          <div class="search-no-results-subtitle">Try different keywords or check your spelling</div>
+          ${note ? `<div class="search-degraded-note">${escapeHtml(note)}</div>` : ""}
+        </div>
+      `;
+      return;
+    }
+
+    this.searchResults.innerHTML = `
+      <div class="search-results-header">Search results (${results.length})</div>
+      ${note ? `<div class="search-degraded-note">${escapeHtml(note)}</div>` : ""}
+      ${results.map((result) => this.createResultHTML(result, query)).join("")}
+    `;
+
+    // Deliberately leaves selectedIndex at -1 (reset above). Auto-selecting the
+    // first hit here would make Enter navigate to it, because handleEnterKey
+    // honors an existing selection before running a search — which would mean
+    // the hybrid query never fires and the semantic path is unreachable. Arrow
+    // keys still select; Enter with nothing selected runs the deliberate search.
+    this.selectableItems = Array.from(this.searchResults.querySelectorAll("[data-url]"));
+  }
+
+  /**
+   * Create HTML for a single search result. A semantic-only hit carries no
+   * snippet (the snippet comes from the full-text row), so its summary block is
+   * omitted entirely rather than rendered empty.
+   */
+  createResultHTML(result, query = "") {
+    const breadcrumb = this.createBreadcrumb(result);
+    const badge = this.createMatchBadge(result);
+    const highlightedTitle = this.highlightKeywords(escapeHtml(result.title), query);
+    const summary = result.snippet
+      ? `<div class="search-result-summary">${this.highlightKeywords(escapeHtml(result.snippet), query)}</div>`
+      : "";
+
+    return `
+      <div class="searched-item" data-url="${escapeHtml(result.url || result.path)}">
+        <i class="search-result-icon"></i>
+        <div class="search-result-content">
+          <div class="search-result-breadcrumb">
+            ${breadcrumb}
+            ${badge}
+          </div>
+          <div class="search-result-title">${highlightedTitle}</div>
+          ${summary}
+        </div>
+        <i class="search-result-goto-icon"></i>
+      </div>
+    `;
+  }
+
+  /**
+   * Whether the hit came from the keyword index, the semantic index, or both —
+   * the reader's cue for why a result with no obvious word match is there.
+   */
+  createMatchBadge(result) {
+    const labels = { keyword: "Keyword", semantic: "Semantic", both: "Keyword + semantic" };
+    // `hasOwn`, not a bare lookup: `matchType` is server-supplied, and
+    // `labels["constructor"]` would otherwise render a function body.
+    if (!Object.hasOwn(labels, result.matchType)) return "";
+    return `<span class="search-match-badge">${labels[result.matchType]}</span>`;
+  }
+
+  /**
+   * Breadcrumb for a search result: the page type of the doc set it belongs to,
+   * followed by the path segments leading to the page.
+   */
+  createBreadcrumb(result) {
+    const facet = searchFacets.find((f) => f.id === result.pageTypeId);
+    // The path STARTS with the set's slug — that is how the server attributed
+    // the hit — so those segments are dropped in favor of the set's name.
+    const rootDepth = facet?.slug ? facet.slug.split("/").filter(Boolean).length : 0;
+    const segments = (result.path || "")
+      .split("/")
+      .filter(Boolean)
+      .slice(rootDepth, -1)
+      .map((segment) => segment.replace(/[-_]/g, " "));
+    const crumbs = facet ? [facet.name, ...segments] : segments;
+
+    return crumbs.map((crumb) => `<span class="search-crumb">${escapeHtml(crumb)}</span>`).join("");
+  }
+
+  /**
+   * Highlight matching keywords in text
+   */
+  highlightKeywords(text, query) {
+    if (!query || !text) return text;
+
+    // Split query into individual words and filter out common words
+    const queryWords = query
+      .toLowerCase()
+      .split(/\s+/)
+      .filter((word) => word.length > 2)
+      .filter((word) => !STOP_WORDS.includes(word));
+
+    if (queryWords.length === 0) {
+      return text;
+    }
+
+    const pattern = new RegExp(`(${queryWords.map((word) => this.escapeRegExp(word)).join("|")})`, "gi");
+
+    return text.replace(pattern, '<span class="search-highlight">$1</span>');
+  }
+
+  /**
+   * Escape special regex characters
+   */
+  escapeRegExp(string) {
+    return string.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  }
+
+  /**
+   * Show recent searches from history
+   */
+  showRecentSearches() {
+    this.resetSelection();
+
+    if (this.searchHistory.length === 0) {
+      this.searchResults.innerHTML = `
+                <div class="search-recent-header">Recent searches</div>
+                <div class="search-no-results">
+                    <div class="search-no-results-subtitle">No recent searches</div>
+                </div>
+            `;
+      return;
+    }
+
+    const historyHTML = this.searchHistory
+      .map((item) => {
+        const timeAgo = this.getTimeAgo(item.timestamp);
+        return `
+                <div class="searched-item search-history-item" data-query="${escapeHtml(item.query)}">
+                    <i class="search-history-icon"></i>
+                    <div class="search-result-content">
+                        <div class="search-result-title">${escapeHtml(item.query)}</div>
+                        <div class="search-result-summary">Searched ${timeAgo}</div>
+                    </div>
+                    <i class="search-result-goto-icon"></i>
+                </div>
+            `;
+      })
+      .join("");
+
+    this.searchResults.innerHTML = `
+            <div class="search-recent-header">Recent searches</div>
+            ${historyHTML}
+        `;
+
+    this.selectableItems = Array.from(this.searchResults.querySelectorAll("[data-query]"));
+
+    if (this.selectableItems.length > 0) {
+      this.selectedIndex = 0;
+      this.updateSelection();
+    }
+  }
+
+  /**
+   * Get human-readable time ago string
+   */
+  getTimeAgo(timestamp) {
+    const now = Date.now();
+    const diff = now - timestamp;
+    const minutes = Math.floor(diff / 60000);
+    const hours = Math.floor(diff / 3600000);
+    const days = Math.floor(diff / 86400000);
+
+    if (minutes < 1) {
+      return "just now";
+    }
+    if (minutes < 60) {
+      return `${minutes} minute${minutes === 1 ? "" : "s"} ago`;
+    }
+    if (hours < 24) {
+      return `${hours} hour${hours === 1 ? "" : "s"} ago`;
+    }
+
+    return `${days} day${days === 1 ? "" : "s"} ago`;
+  }
+}
+
+/** Short, high-frequency words that are noise when highlighting a match. */
+const STOP_WORDS = [
+  "the",
+  "and",
+  "for",
+  "are",
+  "but",
+  "not",
+  "you",
+  "all",
+  "can",
+  "had",
+  "her",
+  "was",
+  "one",
+  "our",
+  "out",
+  "day",
+  "get",
+  "has",
+  "him",
+  "his",
+  "how",
+  "its",
+  "may",
+  "new",
+  "now",
+  "old",
+  "see",
+  "two",
+  "way",
+  "who",
+  "boy",
+  "did",
+  "man",
+  "oil",
+  "sit",
+  "try",
+  "use",
+];
+
+// Global search UI instance with configurable options
+const searchUI = new SearchUI({
+  maxHistoryItems: 7, // Number of recent searches to keep
+  historyStorageKey: "leedSearchHistory", // localStorage key
+});
+
+// Auto-initialize search when DOM is ready
+if (typeof document !== "undefined") {
+  function initializeSearchUI() {
+    if (!initializeSearch()) {
+      return;
+    }
+
+    searchUI.initialize();
+
+    // Only add global Ctrl+K handler if search initialization was successful
+    document.addEventListener(
+      "keydown",
+      (e) => {
+        if (e.ctrlKey && e.key === "k") {
+          e.preventDefault();
+          e.stopPropagation();
+
+          const searchModal = document.getElementById("document-search-modal");
+          if (searchModal && window.Alpine) {
+            // Find the parent Alpine.js component that contains headerSearchShow
+            let currentElement = searchModal;
+            let alpineData = null;
+
+            while (currentElement && currentElement !== document.body) {
+              alpineData = Alpine.$data(currentElement);
+              if (alpineData && typeof alpineData.headerSearchShow !== "undefined") {
+                alpineData.headerSearchShow = true;
+                openSearchInput();
+                return;
+              }
+              currentElement = currentElement.parentElement;
+            }
+
+            if (!alpineData || typeof alpineData.headerSearchShow === "undefined") {
+              const allElements = document.querySelectorAll("[x-data]");
+              for (const element of allElements) {
+                const data = Alpine.$data(element);
+                if (data && typeof data.headerSearchShow !== "undefined") {
+                  data.headerSearchShow = true;
+                  openSearchInput();
+                  return;
+                }
+              }
+            }
+          }
+        }
+      },
+      true,
+    ); // Use capture phase to intercept before other handlers
+  }
+
+  /** Clear the input and show recent searches once the modal has been revealed. */
+  function openSearchInput() {
+    // Ctrl+K opens the modal without touching the trigger, so the chips have to
+    // be requested here too. Both paths are idempotent — `loadFacets` fetches
+    // at most once per page view.
+    searchUI.loadFilters();
+    setTimeout(() => {
+      const searchInput = document.querySelector('#document-search-modal input[type="text"]');
+      if (searchInput) {
+        searchInput.value = "";
+        searchInput.focus();
+        searchUI.showRecentSearches();
+      }
+    }, 50);
+  }
+
+  if (document.readyState === "loading") {
+    document.addEventListener("DOMContentLoaded", initializeSearchUI);
+  } else {
+    initializeSearchUI();
+  }
+}