@mohasinac/appkit 4.52.5 → 4.53.1

package/dist/features/search/components/SearchResultsClient.js

@@ -0,0 +1,103 @@
+"use client";
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+/*
+ * WHY: `/search` should answer from the local artifact — every type, mid-word
+ *      matching, exact counts, zero Firestore reads — while still rendering
+ *      something when the artifact is off or unreachable.
+ * WHAT: The client wrapper around `SearchResultsPageView`. Picks the tier,
+ *       owns the facet selection, and renders the rail.
+ *
+ * ## 🛑 The server result is a FALLBACK, not a first paint to be replaced
+ *
+ * `/search/page.tsx` does NOT run the Firestore fan-out when the index is
+ * enabled — it passes an empty envelope and 0 reads. So `initialResult` is
+ * meaningful only in the kill-switch case, and swapping a populated server
+ * result out from under the user is a flicker that cannot happen here.
+ *
+ * That is also why `loading` renders a waiting line rather than the empty
+ * state: with no server result behind it, an empty state would say "nothing
+ * matched" about a query nobody has finished asking (the `GatedPrice`
+ * three-state discipline, one surface over).
+ *
+ * ## 🛑 Facet selection lives in component state, NOT the URL
+ *
+ * `/search` is `noindex` and every result links out to a real indexable
+ * listing page, so a shareable faceted search URL has no SEO value and would
+ * multiply the crawl trap the page is already careful about. It also keeps
+ * `useUrlTable` out of a page that has no pagination — the one thing the
+ * listing views need it for.
+ *
+ * @tag domain:search
+ * @tag layer:feature
+ * @tag pattern:none
+ * @tag access:client
+ * @tag consumers:app/[locale]/search/page.tsx
+ * @tag sideEffects:network
+ */
+import React from "react";
+import { Text } from "../../../ui/index.js";
+import { useSiteSearch } from "../hooks/useSiteSearch.js";
+import { mergeSearchTiers, useScopedSearch } from "../hooks/useScopedSearch.js";
+import { SearchFacetRail } from "./SearchFacetRail.js";
+import { SearchResultsPageView } from "./SearchResultsPageView.js";
+export function SearchResultsClient({ q, initialResult, indexEnabled, isSignedIn = false, labels, }) {
+    const [selectedFacets, setSelectedFacets] = React.useState([]);
+    // Stable across renders — it is a `useMemo` dependency inside the hook.
+    const label = React.useCallback((typeKey) => labels[typeKey] ?? typeKey, [labels]);
+    /*
+     * `active` is unconditionally true here, unlike the header. Arriving on
+     * `/search?q=…` IS the intent — there is no cheaper signal to wait for,
+     * and gating on focus would mean a page whose entire purpose is results
+     * sits idle until somebody clicks the box.
+     */
+    const local = useSiteSearch(q, {
+        active: true,
+        indexEnabled,
+        facets: selectedFacets,
+        label,
+    });
+    const toggleFacet = React.useCallback((pair) => {
+        setSelectedFacets((prev) => prev.includes(pair) ? prev.filter((p) => p !== pair) : [...prev, pair]);
+    }, []);
+    /*
+     * Tier 2. `submittedQuery` is `q` — the URL parameter — so it changes when
+     * the user SUBMITS, not as they type. That is the whole gating story: the
+     * local tier runs per keystroke because it is free, this one runs per
+     * navigation because it is a bounded Firestore fan-out.
+     */
+    const scoped = useScopedSearch({ enabled: isSignedIn, submittedQuery: q });
+    const usingLocal = local.status === "ready" && local.result !== null;
+    const baseResult = usingLocal && local.result ? local.result : initialResult;
+    const result = React.useMemo(() => scoped.groups.length > 0
+        ? { ...baseResult, groups: mergeSearchTiers(baseResult.groups, scoped.groups) }
+        : baseResult, [baseResult, scoped.groups]);
+    /*
+     * 🛑 A dropped facet selection must not silently keep filtering.
+     *
+     * If the index fails after the user has ticked chips, the fallback result
+     * is unfiltered — so the chips would be lit while doing nothing. Clearing
+     * them is the honest state, and it is cheap because the rail is derived
+     * rather than stored.
+     */
+    React.useEffect(() => {
+        if (!usingLocal && selectedFacets.length > 0)
+            setSelectedFacets([]);
+    }, [usingLocal, selectedFacets.length]);
+    const waiting = local.status === "loading" && q.trim().length > 0;
+    return (_jsx(SearchResultsPageView, { result: waiting ? { ...result, groups: [], totalHits: 0 } : result, footnote: usingLocal && local.builtAt
+            ? `Catalogue index updated ${new Date(local.builtAt).toLocaleString()}.`
+            : undefined, renderAboveGroups: () => (_jsxs(_Fragment, { children: [waiting && _jsx(Text, { color: "muted", children: "Searching\u2026" }), usingLocal && (_jsx(SearchFacetRail, { facets: local.facets, selected: selectedFacets, onToggle: toggleFacet })), scoped.status === "failed" && (
+                /*
+                 * Said out loud, for the same reason as the line below it. A
+                 * seller whose draft is missing because the scoped fetch failed
+                 * will read the silence as "that draft does not exist".
+                 */
+                _jsx(Text, { size: "sm", color: "muted", children: "Couldn't search your account \u2014 results below are public listings only." })), local.status === "failed" && (
+                /*
+                 * Said out loud rather than degraded silently. `searchEverything`'s
+                 * own header records that a degraded source "is indistinguishable
+                 * from 'nothing matched'" — and on a page that otherwise rendered
+                 * fine, silence tells someone we have none of what they asked for.
+                 */
+                _jsx(Text, { size: "sm", color: "muted", children: "Showing a reduced set \u2014 the full catalogue index could not be loaded." }))] })) }));
+}

package/dist/features/search/components/SearchResultsPageView.d.ts

@@ -29,5 +29,19 @@ export interface SearchResultsPageViewProps {
     result: SearchEverythingResult;
     /** Rendered above the groups — the consumer owns the input control. */
     renderSearchInput?: () => React.ReactNode;
+    /**
+     * Rendered between the input and the groups. The facet rail lives here.
+     *
+     * A SLOT rather than a `facets` prop, because this component is also
+     * rendered from a Server Component with no facets at all (the kill-switch
+     * fallback), and a required-looking prop that is absent half the time
+     * invites a `?? []` that silently renders an empty rail.
+     */
+    renderAboveGroups?: () => React.ReactNode;
+    /**
+     * A short line under the heading — "results as of 10:51". Optional because
+     * the server tier has no build time to report.
+     */
+    footnote?: string;
 }
-export declare function SearchResultsPageView({ result, renderSearchInput, }: SearchResultsPageViewProps): React.JSX.Element;
+export declare function SearchResultsPageView({ result, renderSearchInput, renderAboveGroups, footnote, }: SearchResultsPageViewProps): React.JSX.Element;

package/dist/features/search/components/SearchResultsPageView.js

@@ -1,6 +1,7 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { ROUTES } from "../../../next/routing/route-map.js";
 import { Section, Container, Stack, Row, Div, Heading, Text, Span, TextLink } from "../../../ui/index.js";
-export function SearchResultsPageView({ result, renderSearchInput, }) {
+export function SearchResultsPageView({ result, renderSearchInput, renderAboveGroups, footnote, }) {
     const { q, terms, groups, totalHits } = result;
     const hasQuery = q.trim().length > 0;
     /*
@@ -17,5 +18,5 @@ export function SearchResultsPageView({ result, renderSearchInput, }) {
     const normalisedAway = hasQuery && terms.length === 0;
     return (_jsx(Section, { padding: "page", children: _jsx(Container, { children: _jsxs(Stack, { gap: "loose", children: [_jsxs(Stack, { gap: "xs", children: [_jsx(Heading, { level: 1, children: hasQuery ? `Search: ${q}` : "Search" }), hasQuery && !normalisedAway && (_jsx(Text, { color: "muted", size: "sm", children: totalHits === 0
                                     ? "Nothing matched."
-                                    : `${totalHits}${groups.some((g) => g.truncated) ? "+" : ""} result${totalHits === 1 ? "" : "s"} across ${groups.length} section${groups.length === 1 ? "" : "s"}.` }))] }), renderSearchInput?.(), !hasQuery && (_jsx(Text, { color: "muted", children: "Search listings, categories, brands, stores, articles and help pages at once." })), normalisedAway && (_jsx(Text, { color: "muted", children: "That search had no searchable words in it. Try a product, part or category name." })), groups.map((group) => (_jsxs(Stack, { gap: "sm", children: [_jsxs(Row, { justify: "between", align: "center", wrap: true, gap: "sm", children: [_jsxs(Heading, { level: 2, size: "lg", children: [group.label, group.truncated && (_jsxs(Span, { size: "sm", color: "muted", children: [" ", "(", group.hits.length, "+)"] }))] }), _jsxs(TextLink, { href: group.moreHref, children: ["See all ", group.label.toLowerCase(), " \u2192"] })] }), _jsx(Stack, { gap: "xs", children: group.hits.map((hit) => (_jsxs(Div, { surface: "card", padding: "sm", rounded: "md", children: [_jsx(TextLink, { href: hit.href, children: hit.title }), hit.detail && (_jsx(Text, { size: "xs", color: "muted", children: hit.detail }))] }, `${group.key}-${hit.id}`))) })] }, group.key))), hasQuery && !normalisedAway && totalHits === 0 && (_jsxs(Stack, { gap: "xs", children: [_jsxs(Text, { color: "muted", children: ["No listings, categories, brands, stores, articles or help pages matched \u201C", q, "\u201D."] }), _jsx(TextLink, { href: "/products", children: "Browse all listings \u2192" })] }))] }) }) }));
+                                    : `${totalHits}${groups.some((g) => g.truncated) ? "+" : ""} result${totalHits === 1 ? "" : "s"} across ${groups.length} section${groups.length === 1 ? "" : "s"}.` }))] }), footnote && (_jsx(Text, { size: "xs", color: "muted", children: footnote })), renderSearchInput?.(), renderAboveGroups?.(), !hasQuery && (_jsx(Text, { color: "muted", children: "Search listings, categories, brands, stores, articles and help pages at once." })), normalisedAway && (_jsx(Text, { color: "muted", children: "That search had no searchable words in it. Try a product, part or category name." })), groups.map((group) => (_jsxs(Stack, { gap: "sm", children: [_jsxs(Row, { justify: "between", align: "center", wrap: true, gap: "sm", children: [_jsxs(Heading, { level: 2, size: "lg", children: [group.label, group.truncated && (_jsxs(Span, { size: "sm", color: "muted", children: [" ", "(", group.hits.length, "+)"] }))] }), _jsxs(TextLink, { href: group.moreHref, children: ["See all ", group.label.toLowerCase(), " \u2192"] })] }), _jsx(Stack, { gap: "xs", children: group.hits.map((hit) => (_jsxs(Div, { surface: "card", padding: "sm", rounded: "md", children: [_jsx(TextLink, { href: hit.href, children: hit.title }), hit.detail && (_jsx(Text, { size: "xs", color: "muted", children: hit.detail }))] }, `${group.key}-${hit.id}`))) })] }, group.key))), hasQuery && !normalisedAway && totalHits === 0 && (_jsxs(Stack, { gap: "xs", children: [_jsxs(Text, { color: "muted", children: ["No listings, categories, brands, stores, articles or help pages matched \u201C", q, "\u201D."] }), _jsx(TextLink, { href: ROUTES.PUBLIC.PRODUCTS, children: "Browse all listings \u2192" })] }))] }) }) }));
 }

package/dist/features/search/components/index.d.ts

@@ -1,8 +1,2 @@
 export { Search } from "./Search";
 export type { SearchLabels, SearchProps, SearchQuickLink, SearchRouterAdapter, SearchResourceType, SearchResourceTypeOption, } from "./Search";
-export { SearchFiltersRow } from "./SearchFiltersRow";
-export type {} from "./SearchFiltersRow";
-export { SearchResultsSection } from "./SearchResultsSection";
-export type { SearchResultsSectionProps } from "./SearchResultsSection";
-export { SearchView } from "./SearchView";
-export type { SearchViewProps } from "./SearchView";

package/dist/features/search/components/index.js

@@ -1,4 +1 @@
 export { Search } from "./Search.js";
-export { SearchFiltersRow } from "./SearchFiltersRow.js";
-export { SearchResultsSection } from "./SearchResultsSection.js";
-export { SearchView } from "./SearchView.js";

package/dist/features/search/hooks/useNavSuggestions.d.ts

@@ -1,6 +1,19 @@
 export interface NavSuggestionRecord {
     objectID: string;
     type: "page" | "category" | "blog" | "event" | "product";
+    /**
+     * The real index type key (`auction`, `part`, `faq`, `scammer`, …) when the
+     * row came from the local search artifact, which spans 21 types.
+     *
+     * 🛑 `type` above stays a 5-value union on purpose. It is what the
+     * dropdown's `DEFAULT_TYPE_ICONS` / `DEFAULT_TYPE_BADGES` maps switch on,
+     * so widening it would compile everywhere and render 16 types unstyled
+     * (Root Cause #20). `useSiteSearch.suggestionTypeFor` collapses the key
+     * into that union for presentation and puts the precise one here, so a
+     * badge can be specific where a map entry exists without any caller
+     * breaking where one does not.
+     */
+    typeKey?: string;
     title: string;
     subtitle?: string;
     url: string;

package/dist/features/search/hooks/useScopedSearch.d.ts

@@ -0,0 +1,34 @@
+import type { SearchGroup } from "../../../_internal/server/features/search/search-everything";
+export type ScopedSearchStatus = "idle" | "loading" | "ready" | "failed";
+export interface UseScopedSearchResult {
+    readonly status: ScopedSearchStatus;
+    readonly groups: readonly SearchGroup[];
+}
+export interface UseScopedSearchOptions {
+    /** False for a guest. No request is issued at all. */
+    enabled: boolean;
+    /** The committed query. Changing it re-fetches; typing does not. */
+    submittedQuery: string;
+}
+export declare function useScopedSearch({ enabled, submittedQuery, }: UseScopedSearchOptions): UseScopedSearchResult;
+/**
+ * Merge the two tiers.
+ *
+ * ## 🛑 Dedupe by DESTINATION, and local wins
+ *
+ * The tiers are NOT disjoint: a seller's published listing is in the public
+ * artifact AND in `my-listings`. Showing both is a duplicate-results bug;
+ * dropping the public one would lose the row a buyer would see.
+ *
+ * Local wins, so what survives in the scoped group is precisely the rows the
+ * artifact does not have — a seller's DRAFTS. Labelling that group "Your
+ * listings (incl. drafts)" is what makes the dedupe legible rather than
+ * mysterious.
+ *
+ * 🛑 The key is the HREF, not `${typeKey}:${id}`. The artifact keys products
+ * by SLUG and Firestore by document id, so a composite key would never
+ * collide and the dedupe would silently do nothing — the failure mode being
+ * a page that looks fine and shows everything twice. Both tiers already
+ * agree on where a row goes, which is the only identity they share.
+ */
+export declare function mergeSearchTiers(local: readonly SearchGroup[], scoped: readonly SearchGroup[]): SearchGroup[];

package/dist/features/search/hooks/useScopedSearch.js

@@ -0,0 +1,114 @@
+"use client";
+/*
+ * WHY: A signed-in viewer's own records belong in the same box as the public
+ *      catalogue — but they cost real reads and must not be fetched the way
+ *      the free tier is.
+ * WHAT: Tier 2's client half, plus the merge with Tier 1.
+ *
+ * ## 🛑 ON SUBMIT, never per keystroke
+ *
+ * Tier 1 is a local scan and costs nothing, so it runs on every character.
+ * This one is a bounded Firestore fan-out — up to ~320 documents for an
+ * admin — so it runs when the user commits to a query. A debounced
+ * per-keystroke version of this endpoint is how a 50k/day read tier
+ * disappears in an afternoon.
+ *
+ * ## 🛑 A guest issues ZERO requests
+ *
+ * Gated on `enabled`, which the caller sets from the session. The server
+ * refuses too (`auth: true`, and `scopedSourcesFor(null)` is `[]`), but the
+ * client gate is what makes "signed out = no authenticated request in the
+ * Network panel" true, which is the only form of that claim anyone can
+ * verify.
+ *
+ * @tag domain:search
+ * @tag layer:feature
+ * @tag pattern:hook
+ * @tag access:client
+ * @tag consumers:SearchResultsClient
+ * @tag sideEffects:network
+ */
+import * as React from "react";
+import { apiClient } from "../../../http/index.js";
+import { normalizeError } from "../../../errors/normalize.js";
+import { SEARCH_ENDPOINTS } from "../../../constants/api-endpoints.js";
+/** Matches the server-side gate, so the two cannot disagree about what is worth asking. */
+const MIN_CHARS = 3;
+export function useScopedSearch({ enabled, submittedQuery, }) {
+    const [status, setStatus] = React.useState("idle");
+    const [groups, setGroups] = React.useState([]);
+    React.useEffect(() => {
+        const q = submittedQuery.trim();
+        if (!enabled || q.length < MIN_CHARS) {
+            setStatus("idle");
+            setGroups([]);
+            return;
+        }
+        /*
+         * An `AbortController` per query, mirroring `useNavSuggestions`. Without
+         * it, a slow response to an earlier query can land after a faster
+         * response to a later one and overwrite it — the user sees results for
+         * something they already moved on from, which looks like the search
+         * returning the wrong thing rather than like a race.
+         */
+        const controller = new AbortController();
+        setStatus("loading");
+        apiClient
+            .get(SEARCH_ENDPOINTS.SCOPED(q), { signal: controller.signal })
+            .then((res) => {
+            if (controller.signal.aborted)
+                return;
+            setGroups(res?.data?.groups ?? []);
+            setStatus("ready");
+        })
+            .catch((err) => {
+            if (controller.signal.aborted)
+                return;
+            const e = normalizeError(err);
+            /*
+             * `failed`, and the CALLER must say so out loud.
+             * `searchEverything`'s own header records that a degraded source "is
+             * indistinguishable from 'nothing matched'" — and on a page where
+             * the public half rendered fine, silence tells a seller their draft
+             * does not exist.
+             */
+            void e;
+            setGroups([]);
+            setStatus("failed");
+        });
+        return () => controller.abort();
+    }, [enabled, submittedQuery]);
+    return { status, groups };
+}
+/**
+ * Merge the two tiers.
+ *
+ * ## 🛑 Dedupe by DESTINATION, and local wins
+ *
+ * The tiers are NOT disjoint: a seller's published listing is in the public
+ * artifact AND in `my-listings`. Showing both is a duplicate-results bug;
+ * dropping the public one would lose the row a buyer would see.
+ *
+ * Local wins, so what survives in the scoped group is precisely the rows the
+ * artifact does not have — a seller's DRAFTS. Labelling that group "Your
+ * listings (incl. drafts)" is what makes the dedupe legible rather than
+ * mysterious.
+ *
+ * 🛑 The key is the HREF, not `${typeKey}:${id}`. The artifact keys products
+ * by SLUG and Firestore by document id, so a composite key would never
+ * collide and the dedupe would silently do nothing — the failure mode being
+ * a page that looks fine and shows everything twice. Both tiers already
+ * agree on where a row goes, which is the only identity they share.
+ */
+export function mergeSearchTiers(local, scoped) {
+    const seen = new Set();
+    for (const g of local)
+        for (const h of g.hits)
+            seen.add(h.href);
+    const deduped = scoped
+        .map((g) => ({ ...g, hits: g.hits.filter((h) => !seen.has(h.href)) }))
+        // A scoped group that is now empty is dropped entirely rather than
+        // rendered as a heading over nothing, which reads as a broken section.
+        .filter((g) => g.hits.length > 0);
+    return [...local, ...deduped];
+}

package/dist/features/search/hooks/useSearchIndex.d.ts

@@ -0,0 +1,34 @@
+import { type SearchIndexArtifact } from "../../../_internal/shared/search/index-record";
+import { type PreparedIndex } from "../../../_internal/shared/search/match";
+export type SearchIndexStatus = "idle" | "loading" | "ready" | "failed" | "disabled";
+export interface LoadedSearchIndex {
+    readonly artifact: SearchIndexArtifact;
+    readonly prepared: PreparedIndex[];
+    readonly version: number;
+    readonly builtAt: string;
+}
+export interface SearchIndexState {
+    readonly status: SearchIndexStatus;
+    readonly index: LoadedSearchIndex | null;
+    /** Present on `failed`. Short, for a log line — never rendered to a user. */
+    readonly reason: string | null;
+}
+/** Reset hook, for the verify script and for a kill-switch flip mid-session. */
+export declare function __resetSearchIndexForTests(): void;
+/** Start the load if it has not started. Idempotent; safe to call per render. */
+export declare function ensureSearchIndex(): Promise<LoadedSearchIndex | null>;
+export interface UseSearchIndexOptions {
+    /**
+     * Flip true when the user shows intent — focus, or the first keypress.
+     * False keeps the hook in `idle` and issues no request at all.
+     */
+    active: boolean;
+    /**
+     * `siteSettings.search?.indexEnabled`. 🛑 Read as `!== false`, so an
+     * undefined settings object — a failed fetch, a stale cached response from
+     * before the field existed — leaves search WORKING. Only an explicit
+     * `false` disables it.
+     */
+    indexEnabled?: boolean;
+}
+export declare function useSearchIndex({ active, indexEnabled, }: UseSearchIndexOptions): SearchIndexState;

package/dist/features/search/hooks/useSearchIndex.js

@@ -0,0 +1,172 @@
+"use client";
+/*
+ * WHY: Fetch the public search artifact exactly once per page session and
+ *      hand every caller the SAME prepared copy, so typing costs nothing.
+ * WHAT: A module-level singleton loader plus the hook that exposes its state.
+ *
+ * ## 🛑 ONE fetch and ONE `prepareIndex`, per page session, shared
+ *
+ * The artifact is ~420 KB and `prepareIndex` normalises ~3,700 titles and
+ * details. Both are cheap once and ruinous per component: the header
+ * dropdown, `/search`, `/parts` and two `/tools` surfaces all want the same
+ * index, and a hook that loaded per mount would download it five times and
+ * re-normalise 18,500 strings. The singleton lives at module scope — not in a
+ * React context — because a context would make every one of those consumers
+ * require a provider they cannot guarantee (Root Cause #20), and the data is
+ * immutable so there is nothing for a provider to coordinate.
+ *
+ * ## 🛑 Nothing loads until somebody intends to search
+ *
+ * `active` gates the fetch, and callers flip it on first focus or first
+ * keypress — never on mount. The action-index route states the rule this
+ * follows: one request per session, never per keystroke. Firing on mount
+ * would put 420 KB on the critical path of every page view for a feature
+ * most visits never touch, which is the opposite of the trade this whole
+ * design exists to make.
+ *
+ * ## 🛑 It NEVER stores the artifact in localStorage
+ *
+ * The service worker holds the bytes, against an `immutable` version-addressed
+ * URL. localStorage is synchronous, ~5 MB, shared with everything else the app
+ * keeps, and would have to be invalidated by hand on every build. The plan
+ * called for keeping the version integer there to skip the manifest hop; that
+ * is dropped deliberately, because the manifest is a ~100-byte 60s-cached
+ * document and a remembered version is wrong exactly when it matters — after
+ * a rebuild — at which point it costs a WASTED 420 KB download instead of
+ * saving a tiny one.
+ *
+ * ## Four states, and `loading` is not `empty`
+ *
+ * Same discipline as `GatedPrice`'s three: a caller must be able to tell "no
+ * matches" from "we have not loaded the haystack yet". Rendering an empty
+ * state while the index is in flight says "nothing matched" about a question
+ * nobody has asked yet.
+ *
+ * `failed` and `disabled` are also distinct, and both mean *fall back to the
+ * server path* rather than *show nothing*.
+ *
+ * @tag domain:search
+ * @tag layer:feature
+ * @tag pattern:hook
+ * @tag access:client
+ * @tag consumers:Search,SearchResultsPageView,/parts,/tools/price-index
+ * @tag sideEffects:network
+ */
+import * as React from "react";
+import { SEARCH_INDEX_SCHEMA_VERSION, } from "../../../_internal/shared/search/index-record.js";
+import { searchArtifactUrl, searchManifestUrl, } from "../../../_internal/shared/search/artifact-url.js";
+import { prepareIndex } from "../../../_internal/shared/search/match.js";
+import { normalizeError } from "../../../errors/normalize.js";
+/**
+ * Read at module scope, exactly as `utils/media-url.ts` does for the same
+ * variable. Next inlines `NEXT_PUBLIC_*` at build time, so this is a constant
+ * in the bundle rather than a runtime lookup.
+ */
+const BUCKET = process.env.NEXT_PUBLIC_FIREBASE_STORAGE_BUCKET ?? "";
+/**
+ * The singleton. `undefined` until the first caller asks; thereafter the same
+ * promise forever, resolving to `null` on any failure.
+ *
+ * 🛑 Resolving to `null` rather than rejecting is deliberate: a rejected
+ * module-scope promise with no attached handler is an unhandled rejection in
+ * every tab where nothing happens to be awaiting it yet.
+ */
+let inflight;
+let failureReason = null;
+/** Reset hook, for the verify script and for a kill-switch flip mid-session. */
+export function __resetSearchIndexForTests() {
+    inflight = undefined;
+    failureReason = null;
+}
+async function fetchJson(url, label) {
+    /*
+     * 🛑 `mode: "cors"`, explicitly, and never `no-cors`.
+     *
+     * A `no-cors` fetch of a cross-origin object yields an OPAQUE response: the
+     * body cannot be read, the status reads as 0, and a 404 is indistinguishable
+     * from a successful empty index — which is this feature's single favourite
+     * failure mode. The bucket carries a CORS entry for the app origins
+     * precisely so this can be `cors` and the status can be real.
+     */
+    const res = await fetch(url, { mode: "cors", credentials: "omit" });
+    if (!res.ok)
+        throw new Error(`${label}: HTTP ${res.status}`);
+    return (await res.json());
+}
+async function load() {
+    try {
+        if (!BUCKET)
+            throw new Error("NEXT_PUBLIC_FIREBASE_STORAGE_BUCKET is unset");
+        const manifest = await fetchJson(searchManifestUrl(BUCKET), "manifest");
+        /*
+         * 🛑 Refuse a schema this build does not understand, rather than render a
+         * half-understood artifact.
+         *
+         * The tuple is positional. A future `[typeIdx, title, detail, slug,
+         * facets, badge]` would parse without error in this build and simply be
+         * read wrong — wrong slugs, wrong hrefs, confidently. The version lives
+         * in the ENVELOPE and not in the URL for exactly this check; falling back
+         * to the server path is always better than being quietly wrong.
+         */
+        if (manifest.schema !== SEARCH_INDEX_SCHEMA_VERSION) {
+            throw new Error(`schema ${manifest.schema} != client ${SEARCH_INDEX_SCHEMA_VERSION}`);
+        }
+        const artifact = await fetchJson(searchArtifactUrl(BUCKET, manifest.version), "artifact");
+        if (artifact.schema !== SEARCH_INDEX_SCHEMA_VERSION) {
+            throw new Error(`artifact schema ${artifact.schema} disagrees with its manifest`);
+        }
+        return {
+            artifact,
+            // Once, here. See the header, and `prepareIndex`'s own 🛑.
+            prepared: [...prepareIndex(artifact)],
+            version: artifact.version,
+            builtAt: artifact.builtAt,
+        };
+    }
+    catch (err) {
+        const n = normalizeError(err);
+        /*
+         * normalizeError FIRST, before the body touches the value — the project-wide
+         * rule, and what audit-catch-normalize is strict-zero about. It also removes
+         * the hand-rolled `err instanceof Error ? … : String(err)` narrowing that
+         * every catch otherwise reinvents slightly differently, which is the whole
+         * reason the helper exists (Root Cause #31).
+         */
+        failureReason = n.message;
+        return null;
+    }
+}
+/** Start the load if it has not started. Idempotent; safe to call per render. */
+export function ensureSearchIndex() {
+    inflight ?? (inflight = load());
+    return inflight;
+}
+export function useSearchIndex({ active, indexEnabled, }) {
+    const enabled = indexEnabled !== false;
+    const [index, setIndex] = React.useState(null);
+    const [settled, setSettled] = React.useState(false);
+    React.useEffect(() => {
+        if (!active || !enabled || settled)
+            return;
+        let alive = true;
+        void ensureSearchIndex().then((loaded) => {
+            if (!alive)
+                return;
+            setIndex(loaded);
+            setSettled(true);
+        });
+        return () => {
+            alive = false;
+        };
+    }, [active, enabled, settled]);
+    const status = !enabled
+        ? "disabled"
+        : !active
+            ? "idle"
+            : !settled
+                ? "loading"
+                : index
+                    ? "ready"
+                    : "failed";
+    return { status, index, reason: status === "failed" ? failureReason : null };
+}

package/dist/features/search/hooks/useSiteSearch.d.ts

@@ -0,0 +1,26 @@
+import { type FacetCount } from "../../../_internal/shared/search/to-groups";
+import { type SearchIndexStatus } from "./useSearchIndex";
+import type { SearchEverythingResult } from "../../../_internal/server/features/search/search-everything";
+import type { NavSuggestionRecord } from "./useNavSuggestions";
+export interface UseSiteSearchOptions {
+    /** Flip true on focus or first keypress. Gates the artifact fetch. */
+    active: boolean;
+    /** `siteSettings.search?.indexEnabled` — read as `!== false`. */
+    indexEnabled?: boolean;
+    /** Restrict to these index type keys. Absent means every type. */
+    types?: readonly string[];
+    /** Require every one of these `k:v` pairs. The facet rail's selection. */
+    facets?: readonly string[];
+    /** `typeKey` -> heading. See `ToGroupsOptions.label`. */
+    label: (typeKey: string) => string;
+}
+export interface UseSiteSearchResult {
+    readonly status: SearchIndexStatus;
+    /** Null until the index is ready; never a fabricated empty result. */
+    readonly result: SearchEverythingResult | null;
+    readonly suggestions: readonly NavSuggestionRecord[];
+    readonly facets: readonly FacetCount[];
+    /** The index build this answered from, for a "results as of" line. */
+    readonly builtAt: string | null;
+}
+export declare function useSiteSearch(query: string, { active, indexEnabled, types, facets, label }: UseSiteSearchOptions): UseSiteSearchResult;