jamdesk 1.1.103 → 1.1.105

package/vendored/components/search/SearchModal.tsx

@@ -1,6 +1,6 @@
 'use client';
 
-import { useEffect, useState, useRef, useCallback, type ReactElement } from 'react';
+import { useEffect, useState, useRef, useCallback, useMemo, type ReactElement } from 'react';
 import { usePathname, useRouter } from 'next/navigation';
 import { getRecentSearches, addRecentSearch, clearRecentSearches } from '@/lib/recent-searches';
 import { useFocusTrap } from '@/hooks/useFocusTrap';
@@ -9,7 +9,7 @@ import { getSuggestions } from '@/lib/search-suggestions';
 import { trackSearch } from '@/lib/analytics-client';
 import { useLinkPrefix } from '@/lib/link-prefix-context';
 import { useProjectSlug } from '@/lib/project-slug-context';
-import type { SearchResult } from '@/lib/search-client';
+import type { SearchResult, SearchGroup } from '@/lib/search-client';
 
 interface PopularPage {
   title: string;
@@ -90,12 +90,57 @@ function NoResultsState({ query, onSuggestionClick }: { query: string; onSuggest
   );
 }
 
+type SearchRow =
+  | { kind: 'page'; group: SearchGroup; result: SearchResult }
+  | { kind: 'section'; group: SearchGroup; result: SearchResult; sectionIndex: number }
+  | { kind: 'expander'; group: SearchGroup; hiddenCount: number };
+
+const VISIBLE_SECTIONS_PER_GROUP = 3;
+
+function flattenGroups(groups: SearchGroup[], expanded: Set<string>): SearchRow[] {
+  const rows: SearchRow[] = [];
+  for (const g of groups) {
+    rows.push({ kind: 'page', group: g, result: g.page });
+    const isExpanded = expanded.has(g.slug);
+    const visible = isExpanded ? g.sections : g.sections.slice(0, VISIBLE_SECTIONS_PER_GROUP);
+    visible.forEach((s, idx) =>
+      rows.push({ kind: 'section', group: g, result: s, sectionIndex: idx }),
+    );
+    const hiddenCount = g.sections.length - visible.length;
+    if (hiddenCount > 0) rows.push({ kind: 'expander', group: g, hiddenCount });
+  }
+  return rows;
+}
+
+/**
+ * Prefer `description` (frontmatter summary) when it contains a query token;
+ * otherwise fall back to the page's intro `content` — that's what Orama
+ * actually scored against, so highlights are guaranteed to render there.
+ */
+function pickHighlightSnippet(
+  description: string | undefined,
+  content: string,
+  query: string,
+): string {
+  if (!description) return content;
+  const tokens = query.toLowerCase().split(/\s+/).filter(Boolean);
+  if (tokens.length === 0) return description;
+  const descLower = description.toLowerCase();
+  return tokens.some(t => descLower.includes(t)) ? description : content;
+}
+
+function countVisibleResults(rows: SearchRow[]): number {
+  return rows.reduce((n, r) => (r.kind === 'expander' ? n : n + 1), 0);
+}
+
 export function SearchModal({ isOpen, onClose, popularPages, onNavigate }: SearchModalProps) {
   const linkPrefix = useLinkPrefix();
   const projectSlug = useProjectSlug();
   const pathname = usePathname() ?? '';
   const [query, setQuery] = useState('');
-  const [results, setResults] = useState<SearchResult[]>([]);
+  const [groups, setGroups] = useState<SearchGroup[]>([]);
+  const [expandedSlugs, setExpandedSlugs] = useState<Set<string>>(new Set());
+  const rows = useMemo(() => flattenGroups(groups, expandedSlugs), [groups, expandedSlugs]);
   const [selectedIndex, setSelectedIndex] = useState(0);
   const [popularIndex, setPopularIndex] = useState(0);
   const [isSearching, setIsSearching] = useState(false);
@@ -108,7 +153,7 @@ export function SearchModal({ isOpen, onClose, popularPages, onNavigate }: Searc
   // Track if user clicked a result (to avoid double-tracking on modal close)
   const hasTrackedRef = useRef(false);
   // Store last search state for tracking on modal close
-  const lastSearchRef = useRef<{ query: string; resultsCount: number } | null>(null);
+  const lastSearchRef = useRef<{ query: string; resultsCount: number; groupCount: number } | null>(null);
 
   // Effective popular pages (use provided or defaults)
   const effectivePopularPages = popularPages?.length ? popularPages : DEFAULT_POPULAR_PAGES;
@@ -137,6 +182,7 @@ export function SearchModal({ isOpen, onClose, popularPages, onNavigate }: Searc
         type: 'search_query',
         query: lastSearchRef.current.query,
         resultsCount: lastSearchRef.current.resultsCount,
+        groupCount: lastSearchRef.current.groupCount,
       });
     }
     // Reset tracking state when modal opens
@@ -192,7 +238,7 @@ export function SearchModal({ isOpen, onClose, popularPages, onNavigate }: Searc
   // Debounced search effect
   useEffect(() => {
     if (!query.trim()) {
-      setResults([]);
+      setGroups([]);
       setIsSearching(false);
       return;
     }
@@ -202,21 +248,25 @@ export function SearchModal({ isOpen, onClose, popularPages, onNavigate }: Searc
 
     const timer = setTimeout(async () => {
       try {
-        const { search, resolveActiveLocale } = await import('@/lib/search-client');
+        const { searchGrouped, resolveActiveLocale } = await import('@/lib/search-client');
         const activeLocale = resolveActiveLocale(pathname);
-        const searchResults = await search(query, 15, activeLocale);
+        const searchResults = await searchGrouped(query, 15, activeLocale);
         if (!cancelled) {
-          setResults(searchResults);
+          setGroups(searchResults);
+          setExpandedSlugs(new Set());
           setSelectedIndex(0);
           // Store search state for tracking on commit (Enter, click, modal close)
           // This avoids tracking intermediate keystrokes like "C", "Co", "Col" when typing "Column"
-          lastSearchRef.current = { query: query.trim(), resultsCount: searchResults.length };
+          const visibleRowCount = countVisibleResults(flattenGroups(searchResults, new Set()));
+          lastSearchRef.current = {
+            query: query.trim(),
+            resultsCount: visibleRowCount,
+            groupCount: searchResults.length,
+          };
         }
       } catch (error) {
         console.error('Search error:', error);
-        if (!cancelled) {
-          setResults([]);
-        }
+        if (!cancelled) setGroups([]);
       } finally {
         if (!cancelled) {
           setIsSearching(false);
@@ -230,30 +280,46 @@ export function SearchModal({ isOpen, onClose, popularPages, onNavigate }: Searc
     };
   }, [query, pathname]);
 
-  // Scroll selected result into view
+  // Scroll selected result into view. Operates only on the results container —
+  // `scrollIntoView` inside a fixed-position modal scrolls every scrollable
+  // ancestor (including the page behind the modal), which is a documented
+  // anti-pattern in CLAUDE.md.
   useEffect(() => {
-    if (results.length === 0) return;
-    const el = document.getElementById(`search-result-${selectedIndex}`);
-    el?.scrollIntoView({ block: 'nearest' });
-  }, [selectedIndex, results.length]);
+    if (rows.length === 0) return;
+    const container = resultsContainerRef.current;
+    if (!container) return;
+    const el = container.querySelector<HTMLElement>(`#search-result-${selectedIndex}`);
+    if (!el) return;
+    const cRect = container.getBoundingClientRect();
+    const eRect = el.getBoundingClientRect();
+    if (eRect.top < cRect.top) {
+      container.scrollTop += eRect.top - cRect.top;
+    } else if (eRect.bottom > cRect.bottom) {
+      container.scrollTop += eRect.bottom - cRect.bottom;
+    }
+  }, [selectedIndex, rows.length]);
 
   // Click handler for a result row. Defined before the keyboard-navigation
   // effect so it can be a stable dep without TDZ issues.
   const handleResultClick = useCallback(
-    (result: SearchResult, index: number) => {
+    (row: Exclude<SearchRow, { kind: 'expander' }>, index: number) => {
+      const result = row.result;
+      const visibleCount = countVisibleResults(rows);
       if (query.trim()) {
         // Track search_query event (the search itself)
         trackSearch(projectSlug, {
           type: 'search_query',
           query: query.trim(),
-          resultsCount: results.length,
+          resultsCount: visibleCount,
+          groupCount: groups.length,
         });
 
         // Track search_click event (the result they clicked)
         trackSearch(projectSlug, {
           type: 'search_click',
           query: query.trim(),
-          resultsCount: results.length,
+          resultsCount: visibleCount,
+          groupCount: groups.length,
           clickedResult: {
             slug: result.slug,
             position: index + 1, // 1-indexed for analytics
@@ -266,36 +332,53 @@ export function SearchModal({ isOpen, onClose, popularPages, onNavigate }: Searc
         addRecentSearch(projectSlug, query.trim());
       }
 
-      const url = `${linkPrefix}/${result.slug}${result.section ? `#${result.section.toLowerCase().replace(/\s+/g, '-')}` : ''}`;
+      const hash =
+        row.kind === 'section' && result.section
+          ? `#${result.section.toLowerCase().replace(/\s+/g, '-')}`
+          : '';
+      const url = `${linkPrefix}/${result.slug}${hash}`;
       onNavigate?.(url);
       router.push(url);
       onClose();
       setQuery('');
-      setResults([]);
+      setGroups([]);
     },
-    [query, projectSlug, results, linkPrefix, onNavigate, router, onClose]
+    [query, projectSlug, rows, groups, linkPrefix, onNavigate, router, onClose],
   );
 
+  const handleExpanderClick = useCallback((slug: string) => {
+    setExpandedSlugs(prev => {
+      const next = new Set(prev);
+      next.add(slug);
+      return next;
+    });
+  }, []);
+
   // Keyboard navigation
   useEffect(() => {
     if (!isOpen) return;
 
     const handleKeyDown = (e: KeyboardEvent) => {
       // When we have search results, navigate through them
-      if (results.length > 0) {
+      if (rows.length > 0) {
         if (e.key === 'ArrowDown') {
           e.preventDefault();
-          setSelectedIndex((prev) => Math.min(prev + 1, results.length - 1));
+          setSelectedIndex((prev) => Math.min(prev + 1, rows.length - 1));
         } else if (e.key === 'ArrowUp') {
           e.preventDefault();
           setSelectedIndex((prev) => Math.max(prev - 1, 0));
-        } else if (e.key === 'Enter' && results[selectedIndex]) {
+        } else if (e.key === 'Enter' && rows[selectedIndex]) {
           e.preventDefault();
-          handleResultClick(results[selectedIndex], selectedIndex);
+          const row = rows[selectedIndex];
+          if (row.kind === 'expander') {
+            handleExpanderClick(row.group.slug);
+          } else {
+            handleResultClick(row, selectedIndex);
+          }
         }
       }
       // When query exists but no results, Enter tracks the zero-result search
-      else if (query.trim() && results.length === 0 && !isSearching && e.key === 'Enter') {
+      else if (query.trim() && rows.length === 0 && !isSearching && e.key === 'Enter') {
         e.preventDefault();
         // Track this as a committed search with zero results
         trackSearch(projectSlug, {
@@ -336,7 +419,7 @@ export function SearchModal({ isOpen, onClose, popularPages, onNavigate }: Searc
 
     document.addEventListener('keydown', handleKeyDown);
     return () => document.removeEventListener('keydown', handleKeyDown);
-  }, [isOpen, query, recentSearches, results, selectedIndex, effectivePopularPages, popularIndex, router, onClose, onNavigate, projectSlug, handleResultClick, isSearching, linkPrefix]);
+  }, [isOpen, query, recentSearches, rows, selectedIndex, effectivePopularPages, popularIndex, router, onClose, onNavigate, projectSlug, handleResultClick, handleExpanderClick, isSearching, linkPrefix]);
 
   const handleClearRecentSearches = () => {
     clearRecentSearches(projectSlug);
@@ -368,7 +451,7 @@ export function SearchModal({ isOpen, onClose, popularPages, onNavigate }: Searc
 
   // Screen reader announcement text
   const getAnnouncementText = () => {
-    if (results.length > 0) return `${results.length} results found`;
+    if (rows.length > 0) return `${countVisibleResults(rows)} results found`;
     if (query.trim() && !isSearching) return 'No results found';
     return '';
   };
@@ -411,7 +494,7 @@ export function SearchModal({ isOpen, onClose, popularPages, onNavigate }: Searc
               autoFocus
               aria-label="Search documentation"
               aria-controls="search-results"
-              aria-activedescendant={results[selectedIndex] ? `search-result-${selectedIndex}` : undefined}
+              aria-activedescendant={rows[selectedIndex] ? `search-result-${selectedIndex}` : undefined}
             />
             <button
               onClick={onClose}
@@ -444,45 +527,70 @@ export function SearchModal({ isOpen, onClose, popularPages, onNavigate }: Searc
               <LoadingSpinner message="Loading search…" />
             ) : isSearching ? (
               <LoadingSpinner message="Searching…" />
-            ) : results.length > 0 ? (
+            ) : rows.length > 0 ? (
               <div className="py-2">
-                {results.map((result, index) => (
-                  <button
-                    id={`search-result-${index}`}
-                    key={result.id}
-                    onClick={() => handleResultClick(result, index)}
-                    role="option"
-                    aria-selected={index === selectedIndex}
-                    className={`w-full px-4 py-2.5 flex items-start gap-3 cursor-pointer transition-colors outline-none focus-visible:ring-2 focus-visible:ring-[var(--color-accent)] focus-visible:ring-inset ${
-                      index === selectedIndex
-                        ? 'bg-[var(--color-bg-secondary)]'
-                        : 'hover:bg-[var(--color-bg-secondary)]'
-                    }`}
-                  >
-                    <i className="fa-solid fa-file-lines h-4 w-4 text-[var(--color-accent)] flex-shrink-0 mt-0.5" aria-hidden="true" />
-                    <div className="flex-1 text-left min-w-0">
-                      <div className="flex items-center gap-2 mb-0.5">
-                        <span className="text-sm text-[var(--color-text-primary)] font-medium truncate">
-                          {highlightMatch(result.title, query)}
-                        </span>
-                        <TypeBadge type={result.type} />
-                        {result.section && (
-                          <>
-                            <i className="fa-solid fa-chevron-right h-2.5 w-2.5 text-[var(--color-text-muted)] flex-shrink-0" aria-hidden="true" />
-                            <span className="text-xs text-[var(--color-text-tertiary)] truncate">
-                              {highlightMatch(result.section, query)}
-                            </span>
-                          </>
+                {rows.map((row, index) => {
+                  const isSelected = index === selectedIndex;
+
+                  if (row.kind === 'expander') {
+                    const label = `+${row.hiddenCount} more section${row.hiddenCount === 1 ? '' : 's'}`;
+                    return (
+                      <button
+                        id={`search-result-${index}`}
+                        key={`expander:${row.group.slug}`}
+                        onClick={() => handleExpanderClick(row.group.slug)}
+                        role="option"
+                        aria-selected={isSelected}
+                        aria-label={label}
+                        className={`w-full pl-10 pr-4 py-1.5 flex items-center gap-2 cursor-pointer transition-colors text-xs text-[var(--color-text-muted)] hover:text-[var(--color-text-primary)] ${
+                          isSelected ? 'bg-[var(--color-bg-secondary)]' : 'hover:bg-[var(--color-bg-secondary)]'
+                        }`}
+                      >
+                        <i className="fa-solid fa-chevron-down h-2.5 w-2.5" aria-hidden="true" />
+                        <span>{label}</span>
+                      </button>
+                    );
+                  }
+                  const snippet = row.kind === 'page'
+                    ? pickHighlightSnippet(row.result.description, row.result.content, query)
+                    : null;
+                  return (
+                    <button
+                      id={`search-result-${index}`}
+                      key={`${row.group.slug}:${row.kind}:${row.result.id}`}
+                      onClick={() => handleResultClick(row, index)}
+                      role="option"
+                      aria-selected={isSelected}
+                      className={`w-full px-4 py-2.5 flex items-start gap-3 cursor-pointer transition-colors outline-none focus-visible:ring-2 focus-visible:ring-[var(--color-accent)] focus-visible:ring-inset ${
+                        isSelected ? 'bg-[var(--color-bg-secondary)]' : 'hover:bg-[var(--color-bg-secondary)]'
+                      } ${row.kind === 'section' ? 'pl-10' : ''}`}
+                    >
+                      {row.kind === 'page' ? (
+                        <i className="fa-solid fa-file-lines h-4 w-4 text-[var(--color-accent)] flex-shrink-0 mt-0.5" aria-hidden="true" />
+                      ) : (
+                        <i className="fa-solid fa-hashtag h-3 w-3 text-[var(--color-text-muted)] flex-shrink-0 mt-1" aria-hidden="true" />
+                      )}
+                      <div className="flex-1 text-left min-w-0">
+                        <div className="flex items-center gap-2 mb-0.5">
+                          <span className={`text-sm truncate ${row.kind === 'page' ? 'text-[var(--color-text-primary)] font-medium' : 'text-[var(--color-text-secondary)]'}`}>
+                            {row.kind === 'page'
+                              ? highlightMatch(row.result.title, query)
+                              : highlightMatch(row.result.section ?? row.result.title, query)}
+                          </span>
+                          {row.kind === 'page' && <TypeBadge type={row.result.type} />}
+                        </div>
+                        {snippet && (
+                          <p className="text-xs text-[var(--color-text-tertiary)] line-clamp-2">{highlightMatch(snippet, query)}</p>
+                        )}
+                        {row.kind === 'section' && row.result.content && (
+                          <p className="text-xs text-[var(--color-text-tertiary)] line-clamp-1">
+                            {highlightMatch(row.result.content, query)}
+                          </p>
                         )}
                       </div>
-                      {result.content && (
-                        <p className="text-xs text-[var(--color-text-tertiary)] line-clamp-2">
-                          {highlightMatch(result.content, query)}
-                        </p>
-                      )}
-                    </div>
-                  </button>
-                ))}
+                    </button>
+                  );
+                })}
               </div>
             ) : query.trim() ? (
               <NoResultsState query={query} onSuggestionClick={setQuery} />

package/vendored/lib/analytics-client.ts

@@ -28,12 +28,14 @@ interface SearchQueryEvent {
   type: 'search_query';
   query: string;
   resultsCount: number;
+  groupCount?: number;
 }
 
 interface SearchClickEvent {
   type: 'search_click';
   query: string;
   resultsCount: number;
+  groupCount?: number;
   clickedResult: {
     slug: string;
     position: number;

package/vendored/lib/search-client.ts

@@ -16,8 +16,19 @@ export interface SearchResult {
   slug: string;
   section?: string;
   type?: 'api' | 'component' | 'guide' | 'help' | 'quickstart';
-  /** Language of the document. Empty string for default-language pages. */
-  locale: string;
+  /**
+   * Language of the document. Empty string for default-language pages.
+   * OPTIONAL because legacy R2 search-data.json files predate this field;
+   * the client treats `undefined` and `''` identically.
+   */
+  locale?: string;
+  /**
+   * True for the canonical page-level document (idx=0). NOT a queryable
+   * Orama field — used only by `pageDocsBySlugLocale` to identify the
+   * page-level doc per (slug, locale). Legacy indexes that lack this field
+   * fall back via the 3-pass inference in `rebuildPageDocsMap`.
+   */
+  isPageLevel?: boolean;
 }
 
 type OramaDb = Orama<{
@@ -56,6 +67,62 @@ let lastParsedData: SearchResult[] | null = null;
 let projectLocalesLowered: ReadonlySet<string> = new Set();
 let indexHasLocaleField = false;
 
+/**
+ * Canonical page-level document per (slug, locale). Rebuilt on every
+ * `initializeSearch` call (BEFORE the fingerprint short-circuit) so the
+ * map can never drift from the committed data. Used by `searchGrouped`
+ * to surface a guaranteed group header regardless of BM25 score.
+ */
+let pageDocsBySlugLocale: Map<string, SearchResult> = new Map();
+
+function mapKey(slug: string, locale: string): string {
+  return `${slug}|${locale}`;
+}
+
+/**
+ * Three-pass page-level inference:
+ *   1. Explicit `isPageLevel === true` (new emitter)
+ *   2. Empty `section` field (legacy emitter, page has intro text)
+ *   3. `id` ends in `-0` (legacy emitter, page starts with a heading)
+ *
+ * First-match wins per (slug, locale).
+ */
+function rebuildPageDocsMap(data: SearchResult[]): void {
+  // Build into a local map and assign at the end so an in-flight reader
+  // can never observe a partial state.
+  const m = new Map<string, SearchResult>();
+  const localeOf = (item: SearchResult) => item.locale ?? '';
+
+  // Pass 1: explicit flag
+  for (const item of data) {
+    if (item.isPageLevel !== true) continue;
+    const key = mapKey(item.slug, localeOf(item));
+    if (!m.has(key)) m.set(key, item);
+  }
+  // Pass 2: section-less docs
+  for (const item of data) {
+    if (item.section) continue;
+    const key = mapKey(item.slug, localeOf(item));
+    if (!m.has(key)) m.set(key, item);
+  }
+  // Pass 3: id ends in `-0` (lowest-idx doc)
+  for (const item of data) {
+    if (!item.id.endsWith('-0')) continue;
+    const key = mapKey(item.slug, localeOf(item));
+    if (!m.has(key)) m.set(key, item);
+  }
+  pageDocsBySlugLocale = m;
+}
+
+/**
+ * Returns the canonical page-level document for the given (slug, locale)
+ * pair, or undefined if the index has no doc for that pair. Used by
+ * `searchGrouped` to construct group headers.
+ */
+export function getPageDocForSlug(slug: string, locale: string): SearchResult | undefined {
+  return pageDocsBySlugLocale.get(mapKey(slug, locale));
+}
+
 /**
  * Cheap fingerprint: count + first/last IDs + a sample of content lengths.
  * Detects new/removed pages AND content edits (which change content length).
@@ -135,6 +202,12 @@ async function buildIndex(data: SearchResult[], etag: string): Promise<void> {
 }
 
 export async function initializeSearch(data: SearchResult[], etag = ''): Promise<void> {
+  // ALWAYS rebuild the page-docs map before any short-circuit. Rebuilding
+  // it here (rather than inside buildIndex) guarantees the map stays
+  // consistent with the input even when Orama build is skipped on a
+  // fingerprint match (ETag re-fetch, modal re-open with same data).
+  rebuildPageDocsMap(data);
+
   const fp = fingerprint(data);
 
   // Skip rebuild if the committed index already matches
@@ -217,6 +290,154 @@ export async function search(
   return docs.slice(0, limit);
 }
 
+/**
+ * A group of search hits collapsed under a single page.
+ *
+ * `page` is always present and represents the group header. Source order:
+ *   1. The canonical page-level doc from `pageDocsBySlugLocale`
+ *   2. (fallback) A page-level hit observed in this query's results
+ *   3. (fallback) A synthesized header derived from the highest-ranked
+ *      matching section
+ *
+ * `sections` excludes the page-level doc and is the FULL score-sorted list
+ * of matched sub-sections. The UI applies the visible cap.
+ */
+export interface SearchGroup {
+  slug: string;
+  page: SearchResult;
+  sections: SearchResult[];
+  totalSections: number;
+}
+
+/**
+ * Same query as `search()` but collapses hits by slug.
+ *
+ * `groupLimit` is the maximum number of groups (pages). Internally
+ * over-fetches up to `groupLimit * 5`, capped at 75, so a page with many
+ * matching sections doesn't starve other pages out of the result set.
+ *
+ * Tail risk: pages with VERY many matching sections (50+) can still
+ * dominate the over-fetch window and crowd out lower-ranked pages.
+ * Acceptable for docs; switch to Orama v3.1's `groupBy` if it becomes an
+ * issue.
+ */
+export async function searchGrouped(
+  query: string,
+  groupLimit = 10,
+  language?: string,
+): Promise<SearchGroup[]> {
+  if (!db) {
+    console.warn('Search database not initialized');
+    return [];
+  }
+  if (!query.trim()) return [];
+
+  const targetLocale = language ?? '';
+  const docFetchLimit = Math.min(groupLimit * 5, 75);
+
+  const results = await oramaSearch(db, {
+    term: query,
+    limit: docFetchLimit,
+    tolerance: 1,
+    boost: { title: 2, section: 1.5, description: 1, content: 0.5 },
+    ...(indexHasLocaleField ? { where: { locale: { eq: targetLocale } } } : {}),
+  });
+
+  let hits = results.hits.map(h => ({
+    doc: h.document as unknown as SearchResult,
+    score: h.score,
+  }));
+
+  // Locale post-filter for legacy indexes that lack the locale field.
+  if (!indexHasLocaleField) {
+    if (targetLocale) {
+      const prefix = `${targetLocale}/`;
+      hits = hits.filter(h => h.doc.slug.startsWith(prefix));
+    } else if (projectLocalesLowered.size > 0) {
+      hits = hits.filter(h => {
+        const firstSeg = h.doc.slug.split('/', 1)[0]?.toLowerCase();
+        return !firstSeg || !projectLocalesLowered.has(firstSeg);
+      });
+    }
+  }
+
+  type Bucket = {
+    slug: string;
+    bestScore: number;
+    pageHit?: SearchResult;
+    sections: { doc: SearchResult; score: number }[];
+  };
+  const bucketsBySlug = new Map<string, Bucket>();
+  const slugOrder: string[] = [];
+
+  for (const { doc, score } of hits) {
+    let bucket = bucketsBySlug.get(doc.slug);
+    if (!bucket) {
+      bucket = { slug: doc.slug, bestScore: score, sections: [] };
+      bucketsBySlug.set(doc.slug, bucket);
+      slugOrder.push(doc.slug);
+    }
+    if (score > bucket.bestScore) bucket.bestScore = score;
+
+    // Identify page-level doc by ID match against the canonical map
+    // rather than `doc.isPageLevel` — robust against Orama field stripping.
+    //
+    // CRITICAL: this lookup MUST use the doc's own locale (defaulting to ''),
+    // NOT `targetLocale`. The map is keyed by `${slug}|${item.locale ?? ''}`
+    // — so legacy docs (no locale field) live at `slug|''` regardless of the
+    // active search locale. Looking up with `targetLocale` would silently
+    // miss the canonical doc on non-default-locale searches, breaking
+    // page-first identification for the exact legacy case the 3-pass
+    // fallback protects.
+    const canonicalId = getPageDocForSlug(doc.slug, doc.locale ?? '')?.id;
+    if (canonicalId && canonicalId === doc.id) {
+      bucket.pageHit = doc;
+    } else {
+      bucket.sections.push({ doc, score });
+    }
+  }
+
+  const topBuckets = slugOrder
+    .map(s => bucketsBySlug.get(s)!)
+    .sort((a, b) => b.bestScore - a.bestScore)
+    .slice(0, groupLimit);
+
+  return topBuckets.map(bucket => {
+    // Use the locale of an actual hit in the bucket to look up the
+    // canonical doc — mirrors the map's keying rule (`item.locale ?? ''`).
+    // Avoids the legacy-index miss where targetLocale='fr' but the map
+    // keyed the slug at `slug|''` because the doc had no locale field.
+    const sampleHit = bucket.pageHit ?? bucket.sections[0]?.doc;
+    const lookupLocale = sampleHit?.locale ?? '';
+    const canonical = getPageDocForSlug(bucket.slug, lookupLocale);
+
+    const synthesized: SearchResult | undefined =
+      !canonical && !bucket.pageHit && bucket.sections[0]
+        ? {
+            ...bucket.sections[0].doc,
+            id: `synth:${bucket.slug}:${encodeURIComponent(query)}`,
+            section: undefined,
+            content: bucket.sections[0].doc.description || bucket.sections[0].doc.content,
+            isPageLevel: true,
+          }
+        : undefined;
+    const page = canonical ?? bucket.pageHit ?? synthesized!;
+
+    // Copy before sorting — bucket.sections is still referenced from
+    // bucketsBySlug; don't mutate it in place.
+    const sortedSections = [...bucket.sections]
+      .sort((a, b) => b.score - a.score)
+      .map(s => s.doc);
+
+    return {
+      slug: bucket.slug,
+      page,
+      sections: sortedSections,
+      totalSections: sortedSections.length,
+    };
+  });
+}
+
 /** @internal Used by tests only */
 export function isInitialized(): boolean {
   return db !== null;

package/vendored/lib/search.ts

@@ -10,6 +10,13 @@ export interface SearchResult {
   content: string;
   slug: string;
   section?: string;
+  /**
+   * True only on the first document emitted for each page (idx === 0).
+   * Closes the gap where client-side grouping infers the page-level entry from
+   * an empty `section` — which fails when pages open with a heading rather
+   * than introductory prose.
+   */
+  isPageLevel?: boolean;
 }
 
 let searchDocuments: SearchResult[] = [];
@@ -94,6 +101,7 @@ export function buildSearchIndex(): SearchResult[] {
               content: cleanContent.substring(0, 300), // Limit content length
               slug: slug,
               section: section.heading || undefined,
+              ...(idx === 0 ? { isPageLevel: true as const } : {}),
             };
 
             documents.push(doc);