@mohasinac/appkit 4.52.5 → 4.53.1

package/dist/features/reviews/repository/reviews.repository.js

@@ -1,7 +1,7 @@
 import { BaseRepository, getFirestoreCount, prepareForFirestore, parseSieveDateValue, } from "../../../providers/db-firebase/index.js";
 import { NotFoundError } from "../../../errors/index.js";
 import { REVIEW_MAX_RATING, REVIEW_MIN_RATING } from "../../../_internal/shared/features/reviews/config.js";
-import { decryptPiiFields, REVIEW_PII_FIELDS, REVIEW_PII_INDEX_MAP, } from "../../../security/index.js";
+import { maskPii, revealPii, REVIEW_PII_FIELDS, REVIEW_PII_INDEX_MAP, } from "../../../security/index.js";
 import { createReviewId, REVIEW_COLLECTION, } from "../schemas/index.js";
 import { buildReviewSearchTxt } from "../../../utils/search-txt-builders.js";
 import { planSearchTxt, beginSearchWindow, emptySearchResult, } from "../../../utils/search-txt-query.js";
@@ -35,12 +35,23 @@ class ReviewRepository extends BaseRepository {
         this.piiFields = REVIEW_PII_FIELDS;
         this.piiIndexMap = REVIEW_PII_INDEX_MAP;
     }
-    decryptSieveResult(result) {
+    /*
+     * 🛑 Was `decryptSieveResult`, an UNCONDITIONAL decrypt on the list path.
+     *
+     * Same defect as the `mapDoc` one and invisible to R3, which only looks at
+     * `mapDoc` — a repository can leak plaintext through any read path, and this
+     * one did it for all three list methods. Renamed rather than deleted because
+     * these three callers are public-facing and genuinely need a displayable
+     * name, so they now take the MASKED form: "R*** K***" rather than the full
+     * name a scraper could harvest alongside every purchase it describes.
+     *
+     * A caller that needs the real name calls `revealReview` on the row it
+     * actually needs, which is one row rather than a page of fifty.
+     */
+    maskSieveResult(result) {
         return {
             ...result,
-            items: result.items.map((item) => decryptPiiFields(item, [
-                ...REVIEW_PII_FIELDS,
-            ])),
+            items: this.maskedReviews(result.items),
         };
     }
     mapDoc(snap) {
@@ -52,13 +63,53 @@ class ReviewRepository extends BaseRepository {
         // forgotten call site away from a leak. `voteHelpful` reads the raw snapshot
         // inside its transaction and is unaffected.
         const { helpfulVoterIds: _voters, ...rest } = raw;
-        return decryptPiiFields(rest, [
-            ...REVIEW_PII_FIELDS,
-        ]);
+        /*
+         * 🛑 The DECRYPT is gone; the STRIP stays, and the distinction matters.
+         *
+         * This is the one R3 subject whose `mapDoc` did something besides decrypt,
+         * so the override survives — which is also why the audit's rule had to be
+         * scoped to mapDoc's own body rather than "a decrypt call anywhere in this
+         * file": the named accessors below call one, and a file-level test would
+         * report this correctly-converted repository as unconverted forever.
+         *
+         * `userName` is now ciphertext to every caller. `maskPublicReview` masks
+         * it for the public list, and it refuses ciphertext by design — so that
+         * path goes through `maskedReview` instead, which decrypts first.
+         */
+        return rest;
     }
-    async create(input) {
+    /** Plaintext PII. **Opt-in and named** — shows up in review and in a grep. */
+    revealReview(doc) {
+        return revealPii(doc, REVIEW_PII_FIELDS);
+    }
+    /** As `revealReview`, for a list read. */
+    revealReviews(docs) {
+        return docs.map((d) => this.revealReview(d));
+    }
+    /**
+     * Masked PII — **the default for any public surface.** Decrypts first, then
+     * masks: `maskName` returns "Anonymous" for a ciphertext input by design, so
+     * handing it a stored `userName` would anonymise every reviewer.
+     */
+    maskedReview(doc) {
+        return maskPii(doc, REVIEW_PII_FIELDS);
+    }
+    /** As `maskedReview`, for a list read. */
+    maskedReviews(docs) {
+        return docs.map((d) => this.maskedReview(d));
+    }
+    /*
+     * 🛑 NOT an `override`. `BaseRepository.create` promises to accept the
+     * CIPHERTEXT shape; this accepts PLAINTEXT and encrypts, and `string` vs
+     * `Encrypted<string>` is incompatible in both directions, so an override is a
+     * TS2416 either way — correctly, because the signatures disagree about what
+     * the caller holds. Returns `ReviewPlain`: it echoes the input rather than
+     * re-reading.
+     */
+    async createReview(input) {
         const firstName = input.userName.split(" ")[0] || input.userName;
         const id = createReviewId(input.productTitle, firstName, new Date());
+        // Plain in, ciphertext out — the write hook encrypts below.
         const reviewData = {
             ...input,
             helpfulCount: 0,
@@ -334,7 +385,7 @@ class ReviewRepository extends BaseRepository {
             defaultPageSize: 10,
             maxPageSize: 50,
         });
-        return this.decryptSieveResult(result);
+        return this.maskSieveResult(result);
     }
     async listForStore(storeId, model) {
         const baseQuery = this.getCollection().where(REVIEW_FIELDS.STORE_ID, "==", storeId);
@@ -343,7 +394,7 @@ class ReviewRepository extends BaseRepository {
             defaultPageSize: 10,
             maxPageSize: 100,
         });
-        return this.decryptSieveResult(result);
+        return this.maskSieveResult(result);
     }
     /**
      * Derived on every write path via `applyWriteHooks`.
@@ -376,7 +427,7 @@ class ReviewRepository extends BaseRepository {
         });
         // Refine BEFORE decrypting: the refine reads `searchTxt`, which is never
         // encrypted, and decrypting rows that are about to be dropped is waste.
-        return this.decryptSieveResult(win.finish(result));
+        return this.maskSieveResult(win.finish(result));
     }
 }
 ReviewRepository.SIEVE_FIELDS = {

package/dist/features/reviews/schemas/firestore.d.ts

@@ -4,6 +4,7 @@
 import type { ReviewStatus } from "../types";
 import type { BaseDocument } from "../../../_internal/shared/types/base-document";
 import type { ListingType } from "../../products/types/index";
+import type { Encrypted, Plaintext } from "../../../security/encrypted";
 /** Runtime-accessible review status values — use instead of bare string literals. */
 export declare const ReviewStatusValues: {
     readonly PENDING: "pending";
@@ -17,6 +18,16 @@ export interface ReviewVideoField {
     trimStart?: number;
     trimEnd?: number;
 }
+/**
+ * `ReviewDocument` with its PII as plain `string` — what the named repository
+ * accessors return, and what a WRITE path accepts (the repository encrypts).
+ *
+ * `Plaintext<T>` is the one definition of this shape; see `security/encrypted.ts`.
+ * It is deliberately NOT distinguishable from a MASKED value — `maskPii`
+ * returns plain strings too, and no type can express "these characters are
+ * asterisks". The distinction is which named method you called.
+ */
+export type ReviewPlain = Plaintext<ReviewDocument>;
 export interface ReviewDocument extends BaseDocument {
     /** Normalized edge-n-gram search field — see appkit/src/utils/search-txt.ts. */
     searchTxt?: string[];
@@ -29,7 +40,7 @@ export interface ReviewDocument extends BaseDocument {
     userId: string;
     /** Firestore document ID of the reviewer (slug like `user-mohsin-c`). Populated on create; used to build profile links. */
     userSlug?: string;
-    userName: string;
+    userName: Encrypted<string>;
     userAvatar?: string;
     rating: number;
     title: string;
@@ -67,7 +78,7 @@ export declare const REVIEW_INDEXED_FIELDS: readonly ["searchTxt", "productId",
 export declare const DEFAULT_REVIEW_DATA: Partial<ReviewDocument>;
 export declare const REVIEW_PUBLIC_FIELDS: readonly ["id", "productId", "userName", "userAvatar", "rating", "title", "comment", "helpfulCount", "verified", "images", "createdAt"];
 export declare const REVIEW_UPDATABLE_FIELDS: readonly ["rating", "title", "comment", "images"];
-export type ReviewCreateInput = Omit<ReviewDocument, "id" | "createdAt" | "updatedAt" | "helpfulCount" | "reportCount" | "moderatorId" | "moderatorNote" | "approvedAt" | "rejectedAt">;
+export type ReviewCreateInput = Omit<ReviewPlain, "id" | "createdAt" | "updatedAt" | "helpfulCount" | "reportCount" | "moderatorId" | "moderatorNote" | "approvedAt" | "rejectedAt">;
 export type ReviewUpdateInput = Partial<Pick<ReviewDocument, (typeof REVIEW_UPDATABLE_FIELDS)[number]>>;
 export type ReviewModerationInput = {
     status: ReviewStatus;

package/dist/features/reviews/schemas/index.d.ts

@@ -367,20 +367,20 @@ export declare const reviewListParamsSchema: z.ZodObject<{
     sort?: string | undefined;
     status?: "pending" | "approved" | "rejected" | undefined;
     page?: number | undefined;
-    perPage?: number | undefined;
     storeId?: string | undefined;
     rating?: number | undefined;
     featured?: boolean | undefined;
     productId?: string | undefined;
     userId?: string | undefined;
+    perPage?: number | undefined;
 }, {
     sort?: string | undefined;
     status?: "pending" | "approved" | "rejected" | undefined;
     page?: number | undefined;
-    perPage?: number | undefined;
     storeId?: string | undefined;
     rating?: number | undefined;
     featured?: boolean | undefined;
     productId?: string | undefined;
     userId?: string | undefined;
+    perPage?: number | undefined;
 }>;

package/dist/features/scams/actions/scam-actions.js

@@ -119,13 +119,25 @@ export async function getSellerTrustStatus(storeId) {
     if (!owner.value)
         return TRUST_STATUS_CLEAR;
     const ownerDoc = owner.value;
+    /*
+     * 🛑 REVEALED — without this, THIS SECURITY CONTROL SILENTLY ALWAYS PASSES.
+     *
+     * `userRepository` is ciphertext-by-default, while the scam registry's
+     * `phones`/`emails` are PLAINTEXT on purpose (decision D1: a victim googles a
+     * UPI id before paying, so SEO is the feature). Comparing ciphertext against
+     * plaintext never matches, so every lookup returned zero rows and
+     * `sellerTrustStatus` answered CLEAR for every seller — including ones
+     * already in the registry. No error, no log, and the one check a buyer
+     * relies on degraded to a constant.
+     */
+    const ownerPlain = userRepository.revealUser(ownerDoc);
     const lookups = [];
-    if (ownerDoc.phoneNumber) {
-        const phone = ownerDoc.phoneNumber;
+    if (ownerPlain.phoneNumber) {
+        const phone = ownerPlain.phoneNumber;
         lookups.push(() => scammerRepository.findByContactField("phones", phone));
     }
-    if (ownerDoc.email) {
-        const email = ownerDoc.email;
+    if (ownerPlain.email) {
+        const email = ownerPlain.email;
         lookups.push(() => scammerRepository.findByContactField("emails", email));
     }
     if (lookups.length === 0)

package/dist/features/scams/components/ScamProfileView.js

@@ -51,7 +51,7 @@ export function ScamProfileView({ scammer, isAuthenticated, incidents = [], comm
     const registryHref = String(ROUTES.PUBLIC.SCAMS);
     const contestLoginHref = `${String(ROUTES.AUTH.LOGIN)}?redirect=${encodeURIComponent(`/scams/${scammer.id}`)}`;
     const scamTypeDef = getScamType(scammer.scamType);
-    return (_jsxs(Main, { children: [_jsx(Div, { className: "border-b appkit-breadcrumb-strip", children: _jsx(Container, { size: "xl", padding: "y-sm", children: _jsx(Breadcrumb, { items: [
+    return (_jsxs(Main, { children: [_jsx(Div, { className: "border-b", children: _jsx(Container, { size: "xl", padding: "y-sm", children: _jsx(Breadcrumb, { items: [
                             { label: "Home", href: "/" },
                             { label: "Scam Registry", href: registryHref },
                             { label: scammer.displayNames[0] ?? "Profile" },

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

@@ -0,0 +1,44 @@
+import React from "react";
+export interface EntityTypeaheadPick {
+    /** The canonical entity's title, as the index holds it. */
+    readonly title: string;
+    /** Its destination, which encodes the slug. */
+    readonly href: string;
+    /** The index type it came from. */
+    readonly typeKey: string;
+    /**
+     * 🛑 What the USER typed, verbatim. See the header — a consumer that
+     * analyses the resolved title instead of this is throwing away the signal
+     * it was built to detect.
+     */
+    readonly rawQuery: string;
+}
+export interface EntityTypeaheadProps {
+    /** Index type keys to search. `["model"]`, `["category"]`, `["part"]`… */
+    types: readonly string[];
+    onPick: (pick: EntityTypeaheadPick) => void;
+    /** `siteSettings.search?.indexEnabled`. Read as `!== false`. */
+    indexEnabled?: boolean;
+    label: string;
+    placeholder?: string;
+    /** Mirrors the field the consumer owns, so the two cannot disagree. */
+    value?: string;
+    onChange?: (value: string) => void;
+    limit?: number;
+    /**
+     * Default `true`: picking a suggestion fills the field with the
+     * canonical title, as every ordinary typeahead does.
+     *
+     * 🛑 Set `false` when the consumer's DOWNSTREAM LOGIC treats a mismatch
+     * between what was typed and the canonical form as a signal rather than
+     * noise — `/tools/authenticity` is the one caller that needs this. Its
+     * engine fires a trademark-evasion warning on a FUZZY match, and that
+     * warning is exactly what filling the field would silence: the engine
+     * would receive "Storm Pegasus" and match it exactly, never learning the
+     * user typed "Pegasis" at all. With this false, a pick still calls
+     * `onPick` (with `rawQuery` intact) but leaves the field exactly as
+     * typed — discovery without consequence.
+     */
+    fillOnPick?: boolean;
+}
+export declare function EntityTypeahead({ types, onPick, indexEnabled, label, placeholder, value, onChange, limit, fillOnPick, }: EntityTypeaheadProps): React.JSX.Element;

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

@@ -0,0 +1,92 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/*
+ * WHY: Three tools need "turn what the user typed into a canonical entity",
+ *      and each wants a different slice. `resolveEntity`'s `types` parameter
+ *      exists for exactly this; this is its UI.
+ * WHAT: A generic index-backed typeahead. Offers canonical names, reports
+ *       BOTH the chosen entity and the raw string the user typed.
+ *
+ * ## 🛑 `onPick` hands back the RAW query as well as the entity
+ *
+ * This is the one thing about the component that is not a convenience.
+ *
+ * `/tools/authenticity` treats a fuzzy name match as EVIDENCE — a near-miss
+ * fires a trademark-evasion warning, and its own source records the case:
+ * "`Pegasis` … resolves as an `alias` hit, and the evasion-spelling warning
+ * (which only fires on a `fuzzy` hit) stays silent." Meanwhile this
+ * component's matcher derives its alias table from a crawl of a counterfeit
+ * seller's 1,277 titles, on the stated insight that "a counterfeiter's
+ * evasion spellings are the same strings a real buyer mistypes."
+ *
+ * Both systems consume the same corpus with OPPOSITE intent: search treats a
+ * counterfeiter's spelling as something to match through, authenticity
+ * treats it as the signal. So if someone types `Pegasis`, picks "Storm
+ * Pegasus" from this dropdown, and the consumer forwards only the resolved
+ * slug, the engine never sees `Pegasis` and the evasion warning is silenced
+ * BY CONSTRUCTION — the tool would confirm a fake using the exact spelling
+ * that indicates one.
+ *
+ * Hence: this component PROPOSES an entity; the consumer must keep passing
+ * what the user actually typed. Enforced from the other side by
+ * `audit-entity-resolver-consumers` R2, which forbids any module under
+ * `features/authenticity/` from importing the matcher at all — which is why
+ * this lives here and reaches that tool as a slot.
+ *
+ * @tag domain:search
+ * @tag layer:feature
+ * @tag pattern:none
+ * @tag access:client
+ * @tag consumers:/tools/authenticity,/tools/price-index
+ * @tag sideEffects:network
+ */
+import React from "react";
+import { Button, Div, Input, Stack, Text } from "../../../ui/index.js";
+import { useSiteSearch } from "../hooks/useSiteSearch.js";
+/** Stable identity — a `useMemo` dependency inside the hook. */
+const passthroughLabel = (typeKey) => typeKey;
+export function EntityTypeahead({ types, onPick, indexEnabled, label, placeholder, value, onChange, limit = 6, fillOnPick = true, }) {
+    const controlled = value !== undefined;
+    const [internal, setInternal] = React.useState("");
+    const query = controlled ? value : internal;
+    const [active, setActive] = React.useState(false);
+    const [dismissed, setDismissed] = React.useState(false);
+    const { status, result } = useSiteSearch(query, {
+        active,
+        indexEnabled,
+        types,
+        label: passthroughLabel,
+    });
+    const hits = result?.groups.flatMap((g) => g.hits) ?? [];
+    const show = !dismissed && status === "ready" && hits.length > 0 && query.trim().length > 0;
+    const setQuery = (next) => {
+        setDismissed(false);
+        if (controlled)
+            onChange?.(next);
+        else
+            setInternal(next);
+    };
+    return (_jsxs(Stack, { gap: "xs", className: "min-w-0", children: [_jsx(Input, { type: "search", value: query, "aria-label": label, placeholder: placeholder, onFocus: () => setActive(true), onChange: (event) => {
+                    setActive(true);
+                    setQuery(event.target.value);
+                } }), show && (_jsxs(Stack, { gap: "xs", className: "min-w-0", children: [_jsx(Text, { size: "xs", color: "muted", children: "Did you mean one of these?" }), hits.slice(0, limit).map((hit) => (_jsxs(Div, { surface: "card", padding: "xs", rounded: "md", border: "subtle", children: [_jsx(Button, { variant: "ghost", size: "sm", onClick: () => {
+                                    /*
+                                     * 🛑 `rawQuery: query` — BEFORE the field is overwritten
+                                     * with the canonical title. Reading it after would hand the
+                                     * consumer the canonical name as "what the user typed",
+                                     * which is the silent version of the bug this whole
+                                     * component's header is about.
+                                     */
+                                    onPick({
+                                        title: hit.title,
+                                        href: hit.href,
+                                        typeKey: result?.groups.find((g) => g.hits.includes(hit))?.key ?? "",
+                                        rawQuery: query,
+                                    });
+                                    // See `fillOnPick`'s 🛑 — skipping this is the whole
+                                    // reason the prop exists, not an inconsistency.
+                                    if (fillOnPick)
+                                        setQuery(hit.title);
+                                    setDismissed(true);
+                                }, children: hit.title }), hit.detail && (_jsx(Text, { size: "xs", color: "muted", children: hit.detail }))] }, hit.id)))] }))] }));
+}

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

@@ -47,5 +47,16 @@ export interface SearchProps {
     resourceTypes?: SearchResourceTypeOption[];
     defaultResourceType?: SearchResourceType;
     storageKey?: string;
+    /**
+     * `siteSettings.search?.indexEnabled`. Read as `!== false`, so an absent
+     * settings object leaves the local index in play.
+     *
+     * When the index answers, the typeahead spends ZERO network requests per
+     * keystroke and spans all 21 indexed types instead of the four
+     * `/api/search/suggestions` can produce. When it is off or has failed, the
+     * component falls back to that endpoint unchanged — which is why
+     * `useNavSuggestions` is still called rather than deleted.
+     */
+    searchIndexEnabled?: boolean;
 }
-export declare function Search({ isOpen, onClose, onSearch, onOpen, value, onChange, placeholder, deferred, debounceMs, onClear, className, router, quickLinks, labels, suggestionTypeIcons, suggestionTypeBadges, resourceTypes, defaultResourceType, storageKey, }: SearchProps): React.JSX.Element | null;
+export declare function Search({ isOpen, onClose, onSearch, onOpen, value, onChange, placeholder, deferred, debounceMs, onClear, className, router, quickLinks, labels, suggestionTypeIcons, suggestionTypeBadges, resourceTypes, defaultResourceType, storageKey, searchIndexEnabled, }: SearchProps): React.JSX.Element | null;

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

@@ -10,6 +10,16 @@ const CLS_ICON_ROW = "w-4 h-4 flex-shrink-0 text-[var(--appkit-color-text-muted)
 const CLS_TRUNCATE = "font-medium truncate";
 import { Button, Div, Input, Li, Row, Select, Span, Stack, Text, Ul } from "../../../ui/index.js";
 import { useNavSuggestions } from "../hooks/useNavSuggestions.js";
+import { useSiteSearch } from "../hooks/useSiteSearch.js";
+/**
+ * The dropdown renders no group headings, so it needs no labels — but
+ * `useSiteSearch` requires one because `/search` does.
+ *
+ * 🛑 Declared at MODULE scope, not inline. It is a `useMemo` dependency
+ * inside the hook, and an inline arrow is a new identity on every render,
+ * which would re-run the scan on every keystroke of an unchanged query.
+ */
+const identityLabel = (typeKey) => typeKey;
 const DEFAULT_TYPE_ICONS = {
     page: "📄",
     category: "🗂️",
@@ -28,7 +38,7 @@ function SuggestionItem({ suggestion, itemIndex, activeIndex, onSelect, onHover,
     const isActive = activeIndex === itemIndex;
     return (_jsx(Li, { children: _jsxs(Button, { type: "button", variant: "ghost", onClick: () => onSelect(suggestion), onMouseEnter: () => onHover(itemIndex), className: `w-full flex items-center gap-[var(--appkit-space-3)] px-[var(--appkit-space-4)] py-[var(--appkit-space-3)] text-left transition-colors border-b border-[var(--appkit-color-border)] last:border-b-0 ${isActive ? "bg-[var(--appkit-color-surface)] bg-[var(--appkit-color-surface-elevated)]" : CLS_HOVER_ROW}`, children: [_jsx(Span, { size: "sm", children: typeIcons[suggestion.type] }), _jsxs(Div, { className: "flex-1 min-w-0", children: [_jsx(Text, { size: "sm", className: CLS_TRUNCATE, children: suggestion.title }), suggestion.subtitle && (_jsx(Text, { variant: "secondary", size: "xs", className: "truncate", children: suggestion.subtitle }))] }), _jsx(Span, { size: "xs", className: `${typeBadges[suggestion.type]}`, rounded: "full", padding: "pill-xs", children: suggestion.type })] }) }));
 }
-export function Search({ isOpen, onClose, onSearch, onOpen, value, onChange, placeholder, deferred = true, debounceMs = 300, onClear, className, router, quickLinks = [], labels, suggestionTypeIcons, suggestionTypeBadges, resourceTypes, defaultResourceType = "products", storageKey = "letitrip_search_type", }) {
+export function Search({ isOpen, onClose, onSearch, onOpen, value, onChange, placeholder, deferred = true, debounceMs = 300, onClear, className, router, quickLinks = [], labels, suggestionTypeIcons, suggestionTypeBadges, resourceTypes, defaultResourceType = "products", storageKey = "letitrip_search_type", searchIndexEnabled, }) {
     const isInlineMode = value !== undefined;
     const [query, setQuery] = useState(isInlineMode ? value : "");
     const [activeIndex, setActiveIndex] = useState(-1);
@@ -37,7 +47,33 @@ export function Search({ isOpen, onClose, onSearch, onOpen, value, onChange, pla
     const inputRef = useRef(null);
     const debounceRef = useRef(null);
     const inlineBlurRef = useRef(null);
-    const { suggestions, isLoading: suggestionsLoading } = useNavSuggestions(query, selectedType);
+    /*
+     * 🛑 BOTH hooks are called unconditionally — React's rules leave no choice,
+     * and it costs nothing here because each one is self-gating.
+     *
+     * `useSiteSearch` is gated on `active`: it issues no request until the user
+     * focuses or types, and then exactly one, for the whole page session.
+     * `useNavSuggestions` is gated on its own 3-character minimum AND on
+     * `remoteQuery` below, which is blank whenever the index is answering — so
+     * the fallback path makes no network request at all in the normal case.
+     */
+    const [searchIntent, setSearchIntent] = useState(false);
+    const local = useSiteSearch(query, {
+        active: searchIntent,
+        indexEnabled: searchIndexEnabled,
+        label: identityLabel,
+    });
+    /*
+     * The index is authoritative the moment it is `ready`. `loading` must NOT
+     * fall through to the remote path: that would fire the very round trips
+     * this replaces, for the one second before the local answer arrives, on
+     * every first keystroke.
+     */
+    const useLocal = local.status === "ready";
+    const remoteQuery = useLocal || local.status === "loading" ? "" : query;
+    const { suggestions: remoteSuggestions, isLoading: remoteLoading } = useNavSuggestions(remoteQuery, selectedType);
+    const suggestions = useLocal ? local.suggestions : remoteSuggestions;
+    const suggestionsLoading = useLocal ? false : local.status === "loading" || remoteLoading;
     const typeIcons = { ...DEFAULT_TYPE_ICONS, ...suggestionTypeIcons };
     const typeBadges = { ...DEFAULT_TYPE_BADGES, ...suggestionTypeBadges };
     // Restore persisted type from localStorage after mount
@@ -90,6 +126,7 @@ export function Search({ isOpen, onClose, onSearch, onOpen, value, onChange, pla
         setActiveIndex(-1);
     }, [isOpen, isInlineMode, query, suggestions.length]);
     const handleInlineChange = (nextValue) => {
+        setSearchIntent(true);
         setQuery(nextValue);
         if (!deferred) {
             if (debounceRef.current)
@@ -209,6 +246,10 @@ export function Search({ isOpen, onClose, onSearch, onOpen, value, onChange, pla
             }
         };
         return (_jsxs(Row, { className: `relative ${className ?? ""}`, gap: "sm", children: [_jsxs(Row, { className: "relative flex-1 min-w-0", children: [_jsx("svg", { className: "absolute left-3 w-4 h-4 text-zinc-400 pointer-events-none", "aria-hidden": "true", fill: "none", stroke: "currentColor", viewBox: "0 0 24 24", children: _jsx("path", { strokeLinecap: "round", strokeLinejoin: "round", strokeWidth: 2, d: SVG_PATH_SEARCH }) }), _jsx(Input, { ref: inputRef, bare: true, type: "search", value: query, onChange: (event) => handleInlineChange(event.target.value), onKeyDown: handleInlineKeyDown, onFocus: () => {
+                                // Focus is the earliest honest signal of intent, and it buys
+                                // the ~900 ms the artifact takes to land before the first
+                                // keystroke needs an answer.
+                                setSearchIntent(true);
                                 if (inlineBlurRef.current)
                                     clearTimeout(inlineBlurRef.current);
                                 setIsInlineOpen(true);
@@ -292,7 +333,10 @@ export function Search({ isOpen, onClose, onSearch, onOpen, value, onChange, pla
     };
     if (!isOpen)
         return null;
-    return (_jsx(Div, { border: "bottom-subtle", className: "animate-[fadeIn_150ms_ease-out]", surface: "default", shadow: "md", children: _jsxs(Div, { className: "container mx-auto md:py-[1rem] relative", padding: "inline", children: [_jsxs(Row, { gap: "sm", className: "md:gap-[0.75rem]", children: [_jsx(Div, { className: "flex-1 relative min-w-0", children: _jsx(Input, { ref: inputRef, bare: true, type: "search", placeholder: placeholder ?? labels.placeholder, value: query, onChange: (event) => setQuery(event.target.value), onKeyDown: handleOverlayKeyDown, className: "w-full rounded-lg border bg-[var(--appkit-color-surface)] text-zinc-900 placeholder:text-zinc-400 focus:border-primary focus:ring-2 focus:ring-primary/20 border-[var(--appkit-color-border)] bg-[var(--appkit-color-surface)] dark:text-white dark:placeholder:text-slate-500" }) }), resourceTypes && resourceTypes.length > 0 && (_jsx(Select, { options: resourceTypes, value: selectedType, onValueChange: handleTypeChange, "aria-label": labels.resourceTypeLabel ?? "Search in", wrapperClassName: "flex-shrink-0 max-w-[92px] sm:max-w-[150px]" })), _jsxs(Button, { gap: "md", onClick: handleOverlaySearch, variant: "primary", size: "md", className: "hidden sm:", children: [_jsx("svg", { className: "w-5 h-5 shrink-0", fill: "none", stroke: "currentColor", viewBox: "0 0 24 24", children: _jsx("path", { strokeLinecap: "round", strokeLinejoin: "round", strokeWidth: 2, d: SVG_PATH_SEARCH }) }), labels.title] }), _jsx(Button, { rounded: "xl", variant: "ghost", onClick: () => onClose?.(), className: "p-[var(--appkit-space-2-5)] md:p-[var(--appkit-space-3)] transition-colors text-[var(--appkit-color-text-muted)] hover:text-zinc-700 text-[var(--appkit-color-text-muted)] hover:bg-surface-hover hover:text-[var(--appkit-color-text-muted)] flex-shrink-0", "aria-label": labels.closeAriaLabel, children: _jsx("svg", { className: "w-6 h-6 md:w-7 md:h-7 shrink-0", fill: "none", stroke: "currentColor", viewBox: "0 0 24 24", children: _jsx("path", { strokeLinecap: "round", strokeLinejoin: "round", strokeWidth: 2, d: "M6 18L18 6M6 6l12 12" }) }) })] }), (filteredSiteLinks.length > 0 || query) && (_jsxs(Stack, { className: "absolute top-full left-0 right-0 z-50 pt-[0.5rem] pb-[1rem]", padding: "x-md", gap: "sm", children: [filteredSiteLinks.length > 0 && !suggestionsLoading && (_jsxs(Div, { className: `${__O.hidden}`, rounded: "xl", shadow: "lg", surface: "default", border: "default", children: [_jsx(Div, { border: "default", className: "border-b", paddingY: "y-xs", paddingX: "x-md", children: _jsx(Text, { variant: "secondary", size: "xs", className: "uppercase tracking-wider", weight: "semibold", children: labels.quickLinks }) }), _jsx(Ul, { children: filteredSiteLinks.map((link) => {
+    return (_jsx(Div, { border: "bottom-subtle", className: "animate-[fadeIn_150ms_ease-out]", surface: "default", shadow: "md", children: _jsxs(Div, { className: "container mx-auto md:py-[1rem] relative", padding: "inline", children: [_jsxs(Row, { gap: "sm", className: "md:gap-[0.75rem]", children: [_jsx(Div, { className: "flex-1 relative min-w-0", children: _jsx(Input, { ref: inputRef, bare: true, type: "search", placeholder: placeholder ?? labels.placeholder, value: query, onFocus: () => setSearchIntent(true), onChange: (event) => {
+                                    setSearchIntent(true);
+                                    setQuery(event.target.value);
+                                }, onKeyDown: handleOverlayKeyDown, className: "w-full rounded-lg border bg-[var(--appkit-color-surface)] text-zinc-900 placeholder:text-zinc-400 focus:border-primary focus:ring-2 focus:ring-primary/20 border-[var(--appkit-color-border)] bg-[var(--appkit-color-surface)] dark:text-white dark:placeholder:text-slate-500" }) }), resourceTypes && resourceTypes.length > 0 && (_jsx(Select, { options: resourceTypes, value: selectedType, onValueChange: handleTypeChange, "aria-label": labels.resourceTypeLabel ?? "Search in", wrapperClassName: "flex-shrink-0 max-w-[92px] sm:max-w-[150px]" })), _jsxs(Button, { gap: "md", onClick: handleOverlaySearch, variant: "primary", size: "md", className: "hidden sm:", children: [_jsx("svg", { className: "w-5 h-5 shrink-0", fill: "none", stroke: "currentColor", viewBox: "0 0 24 24", children: _jsx("path", { strokeLinecap: "round", strokeLinejoin: "round", strokeWidth: 2, d: SVG_PATH_SEARCH }) }), labels.title] }), _jsx(Button, { rounded: "xl", variant: "ghost", onClick: () => onClose?.(), className: "p-[var(--appkit-space-2-5)] md:p-[var(--appkit-space-3)] transition-colors text-[var(--appkit-color-text-muted)] hover:bg-surface-hover hover:text-[var(--appkit-color-text)] flex-shrink-0", "aria-label": labels.closeAriaLabel, children: _jsx("svg", { className: "w-6 h-6 md:w-7 md:h-7 shrink-0", fill: "none", stroke: "currentColor", viewBox: "0 0 24 24", children: _jsx("path", { strokeLinecap: "round", strokeLinejoin: "round", strokeWidth: 2, d: "M6 18L18 6M6 6l12 12" }) }) })] }), (filteredSiteLinks.length > 0 || query) && (_jsxs(Stack, { className: "absolute top-full left-0 right-0 z-50 pt-[0.5rem] pb-[1rem]", padding: "x-md", gap: "sm", children: [filteredSiteLinks.length > 0 && !suggestionsLoading && (_jsxs(Div, { className: `${__O.hidden}`, rounded: "xl", shadow: "lg", surface: "default", border: "default", children: [_jsx(Div, { border: "default", className: "border-b", paddingY: "y-xs", paddingX: "x-md", children: _jsx(Text, { variant: "secondary", size: "xs", className: "uppercase tracking-wider", weight: "semibold", children: labels.quickLinks }) }), _jsx(Ul, { children: filteredSiteLinks.map((link) => {
                                         const Icon = link.icon;
                                         const itemIndex = quickLinkItems.findIndex((item) => item.link.href === link.href);
                                         const isActive = activeIndex === itemIndex;

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

@@ -0,0 +1,11 @@
+import React from "react";
+import type { FacetCount } from "../../../_internal/shared/search/to-groups";
+export interface SearchFacetRailProps {
+    facets: readonly FacetCount[];
+    /** Currently applied `k:v` pairs. */
+    selected: readonly string[];
+    onToggle: (pair: string) => void;
+    /** Values shown per key before the rest are hidden. */
+    maxPerKey?: number;
+}
+export declare function SearchFacetRail({ facets, selected, onToggle, maxPerKey, }: SearchFacetRailProps): React.JSX.Element | null;

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

@@ -0,0 +1,92 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/*
+ * WHY: Refining a 3,700-record local result set is free; refining a Firestore
+ *      one is an aggregation query per facet value plus a composite index per
+ *      shape. This rail only exists because Tier 1 made it cost nothing.
+ * WHAT: Toggleable `k:v` facet chips with live counts over the CURRENT hits.
+ *
+ * ## 🛑 Counts are over the current result set, not the catalogue
+ *
+ * Tick one chip and the others shrink, truthfully, because every number is a
+ * reduce over the hits the query just produced. `BaseRepository.facetCounts`
+ * cannot do this — it counts the collection, one aggregation query per value,
+ * and returns `undefined` on a missing index so the chip renders with no
+ * number at all. A count that can silently vanish is worse than no rail.
+ *
+ * ## 🛑 A chip whose count would be zero is not rendered
+ *
+ * It cannot be: the counts come from the hits, so a value with no hits has no
+ * entry. That is the structural version of Root Cause #72's rule — there, a
+ * hide-when-empty tab survived because its count map returned `undefined`
+ * ("unknown") rather than `0`, so four tabs were unhideable. Here there is no
+ * count map to be incomplete.
+ *
+ * @tag domain:search
+ * @tag layer:feature
+ * @tag pattern:none
+ * @tag access:client
+ * @tag consumers:SearchResultsClient
+ * @tag sideEffects:none
+ */
+import React from "react";
+import { Button, Div, Row, Span, Stack, Text } from "../../../ui/index.js";
+/**
+ * Short code -> heading.
+ *
+ * 🛑 `Partial`, and an unknown code is SKIPPED rather than shown raw. The
+ * codes are two letters to keep the artifact small (`lt:auction` over
+ * `listingType:auction`, ×3,700), which means a new one added on the builder
+ * side would otherwise surface to a visitor as a heading reading "sz". A
+ * facet nobody can name is not a refinement, and dropping it loses nothing
+ * the groups above do not already show.
+ */
+const FACET_KEY_LABEL = {
+    lt: "Type",
+    br: "Brand",
+    cn: "Condition",
+    fr: "Franchise",
+    ct: "Category",
+};
+/** Slug -> words. The artifact stores slugs; nobody wants to read one. */
+function humanise(value) {
+    const spaced = value.replace(/[-_]/g, " ");
+    return spaced.charAt(0).toUpperCase() + spaced.slice(1);
+}
+export function SearchFacetRail({ facets, selected, onToggle, maxPerKey = 6, }) {
+    const selectedSet = React.useMemo(() => new Set(selected), [selected]);
+    const byKey = React.useMemo(() => {
+        const map = new Map();
+        for (const f of facets) {
+            if (!FACET_KEY_LABEL[f.key])
+                continue; // see FACET_KEY_LABEL's 🛑
+            const bucket = map.get(f.key);
+            if (bucket)
+                bucket.push(f);
+            else
+                map.set(f.key, [f]);
+        }
+        return map;
+    }, [facets]);
+    /*
+     * A key offering ONE value is not a refinement — every result already has
+     * it, so ticking it changes nothing and the chip is pure noise. The
+     * exception is a value already selected: hiding the chip you used to narrow
+     * the page would leave no way to un-narrow it.
+     */
+    const keys = [...byKey.keys()].filter((k) => {
+        const values = byKey.get(k) ?? [];
+        return values.length > 1 || values.some((v) => selectedSet.has(`${v.key}:${v.value}`));
+    });
+    if (keys.length === 0)
+        return null;
+    return (_jsx(Stack, { gap: "sm", children: keys.map((key) => {
+            const values = byKey.get(key) ?? [];
+            const shown = values.slice(0, maxPerKey);
+            return (_jsxs(Stack, { gap: "xs", children: [_jsx(Text, { size: "xs", color: "muted", weight: "semibold", transform: "uppercase", children: FACET_KEY_LABEL[key] }), _jsxs(Row, { wrap: true, gap: "xs", children: [shown.map((f) => {
+                                const pair = `${f.key}:${f.value}`;
+                                const isOn = selectedSet.has(pair);
+                                return (_jsxs(Button, { size: "sm", variant: isOn ? "primary" : "outline", "aria-pressed": isOn, onClick: () => onToggle(pair), children: [humanise(f.value), _jsxs(Span, { size: "xs", color: isOn ? "inherit" : "muted", numeric: true, children: [" ", f.count] })] }, pair));
+                            }), values.length > shown.length && (_jsx(Div, { padding: "xs", children: _jsxs(Text, { size: "xs", color: "muted", children: ["+", values.length - shown.length, " more"] }) }))] })] }, key));
+        }) }));
+}

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

@@ -0,0 +1,33 @@
+import React from "react";
+import type { SearchEverythingResult } from "../../../_internal/server/features/search/search-everything";
+export interface SearchResultsClientProps {
+    /** The query, resolved server-side from `?q=`. */
+    q: string;
+    /**
+     * The Tier 2 result. Empty (and unread) whenever `indexEnabled` is true —
+     * see the header.
+     */
+    initialResult: SearchEverythingResult;
+    indexEnabled: boolean;
+    /**
+     * Whether a session exists. FALSE for a guest, and that is what makes
+     * "signed out issues zero authenticated requests" verifiable in the
+     * Network panel rather than merely true on the server.
+     */
+    isSignedIn?: boolean;
+    /**
+     * `typeKey` -> heading.
+     *
+     * 🛑 A plain OBJECT, not a `(key: string) => string`. This component is
+     * rendered from a Server Component, and a function prop is not
+     * serialisable across the RSC boundary — it throws at render, not at
+     * compile. Same constraint `HomepageSectionBoundary` documents for its
+     * `sectionId`/`sectionType` strings.
+     *
+     * A key with no entry falls back to the key itself rather than being
+     * dropped: a group headed `scammer` is ugly, a group that silently
+     * disappears is a bug.
+     */
+    labels: Readonly<Record<string, string>>;
+}
+export declare function SearchResultsClient({ q, initialResult, indexEnabled, isSignedIn, labels, }: SearchResultsClientProps): React.JSX.Element;