@mohasinac/appkit 4.52.5 → 4.53.1

package/dist/_internal/shared/search/match.js

@@ -0,0 +1,264 @@
+/*
+ * WHY: Searching a 3,730-record artifact in the browser, at zero Firestore
+ *      reads per keystroke. The action-index route already states the
+ *      doctrine this follows: "One request per session per portal, never per
+ *      keystroke… a typeahead has to answer in under 16 ms, which a network
+ *      hop cannot."
+ * WHAT: A pure, isomorphic matcher plus `resolveEntity`, the named primitive
+ *       the /tools surfaces call.
+ *
+ * ## 🛑 ONE normaliser, and it is imported, not reimplemented
+ *
+ * `normalizeSearchText` is the same function the write path and the Firestore
+ * path use. `audit-search-parity`'s R2 exists because a second tokeniser
+ * writes tokens the query side cannot match — "and re-running the backfill
+ * does NOT fix it". A library would have brought a third; this file must not
+ * grow a local lowercase/NFD pipeline. Enforced by that audit.
+ *
+ * ## Why hand-rolled rather than MiniSearch
+ *
+ * Three reasons, in order of weight:
+ *
+ *  1. the normaliser argument above;
+ *  2. typo tolerance is already solved at WRITE time with evidence —
+ *     `alias-variants` derives its suffix swaps from a crawl of a counterfeit
+ *     seller's 1,277 titles, which is better grounded than generic edit
+ *     distance and costs nothing at query time;
+ *  3. ~3,700 records is below where an inverted index earns its complexity. A
+ *     linear scan is a few thousand cheap iterations.
+ *
+ * 🛑 (3) is a claim with a number attached, and the number is checked —
+ * `scripts/verify-search-local.mjs` times it and prints the result. If that
+ * ever stops being true, this comment is the thing to come back and delete.
+ *
+ * ## 🛑 It is NOT BM25 and must not be described as BM25
+ *
+ * BM25's two moving parts are IDF and length normalisation. Titles here
+ * average 20 characters, so length normalisation is degenerate; IDF over one
+ * domain mostly re-derives "beyblade is common", which `weight` already
+ * encodes. Calling an ordered weight sum "BM25-ish" would be decoration
+ * (Root Cause #92). It is a weighted match score, the weights are below, and
+ * they are tuned against the verify script.
+ *
+ * ## What this has that the Firestore path structurally cannot
+ *
+ * SUBSTRING. `search-txt.ts` states the limit outright: "Word-prefix, not
+ * mid-word. 'ariza' will not match 'charizard'." A linear scan gets mid-word
+ * for free, which is why Tier 1 is better at its job than Tier 2, not merely
+ * cheaper.
+ *
+ * @tag domain:search
+ * @tag layer:shared
+ * @tag pattern:none
+ * @tag access:isomorphic
+ * @tag consumers:useSiteSearch,/parts,/tools/price-index,verify-search-local
+ * @tag sideEffects:none
+ */
+import { normalizeSearchText, parseSearchTxtQuery } from "../../../utils/search-txt.js";
+import { aliasVariantsForName } from "./alias-variants.js";
+import { partAliasTokens } from "./part-aliases.js";
+import { facetsOf, hrefFor, REC_DETAIL, REC_FACETS, REC_TITLE, REC_TYPE, } from "./index-record.js";
+/** Field weights. Title dominates; a detail match is corroboration. */
+const W_TITLE = 3;
+const W_DETAIL = 1;
+/** Match-quality weights, highest first. */
+const S_EXACT = 100;
+const S_PREFIX = 60;
+const S_SUBSTRING = 30;
+const S_ALIAS = 15;
+/** Default cap. A dropdown shows ~6 per group; a page shows more. */
+const DEFAULT_LIMIT = 50;
+/**
+ * Prepare an artifact for searching.
+ *
+ * 🛑 Call this ONCE per artifact, not per query. It normalises every title and
+ * detail up front — ~3,700 × 2 `normalizeSearchText` calls, a few milliseconds
+ * — so that the per-keystroke path does no allocation beyond the query's own
+ * terms. Doing it inside `search` would move that cost onto every keystroke,
+ * which is the one thing this design exists to avoid.
+ */
+export function prepareIndex(artifact) {
+    return artifact.r.map((rec) => {
+        const title = rec[REC_TITLE] ?? "";
+        const titleFlat = normalizeSearchText(title);
+        const detailFlat = normalizeSearchText(rec[REC_DETAIL] ?? "");
+        /*
+         * 🛑 The alias corpus is expanded against the DOCUMENT, not the query, and
+         * getting this backwards is a real bug I shipped into the first draft.
+         *
+         * `aliasVariantsForName` is DIRECTIONAL: `doubledLetterVariants` collapses
+         * `dragoon -> dragon`, it does not expand `dragon -> dragoon`. The
+         * Firestore path works because `buildProductSearchTxt` runs it over the
+         * TITLE at write time, so the document carries "dragon" as a token.
+         * Expanding the query instead produces nothing for that rule, and the
+         * verify script caught it: searching "dragon" found no "Dragoon Storm".
+         *
+         * So the client does at LOAD what the server does at WRITE — same
+         * function, same direction, same result. It also keeps the variants out
+         * of the artifact, which is why `index-record.ts` does not carry them.
+         *
+         * `partAliasTokens` is symmetric (a code <-> name table), so it would have
+         * worked either way; it runs here too so there is one rule, not two.
+         */
+        const aliasSet = new Set();
+        for (const v of aliasVariantsForName(title))
+            aliasSet.add(normalizeSearchText(v));
+        for (const v of partAliasTokens(`${title} ${rec[REC_DETAIL] ?? ""}`)) {
+            aliasSet.add(normalizeSearchText(v));
+        }
+        aliasSet.delete(titleFlat); // a variant identical to the title adds nothing
+        const aliasFlat = [...aliasSet].filter(Boolean).join(" ");
+        return {
+            rec,
+            titleFlat,
+            detailFlat,
+            aliasFlat,
+            titleWords: titleFlat ? titleFlat.split(" ") : [],
+            detailWords: detailFlat ? detailFlat.split(" ") : [],
+            aliasWords: aliasFlat ? aliasFlat.split(" ") : [],
+        };
+    });
+}
+/** Best match quality for one term against one field. 0 means no match. */
+function fieldScore(term, words, flat) {
+    if (!flat)
+        return 0;
+    for (const w of words)
+        if (w === term)
+            return S_EXACT;
+    for (const w of words)
+        if (w.startsWith(term))
+            return S_PREFIX;
+    // Mid-word. The capability the token index cannot have.
+    if (flat.includes(term))
+        return S_SUBSTRING;
+    return 0;
+}
+function recordScore(p, terms, typeWeight) {
+    let total = 0;
+    for (const term of terms) {
+        /*
+         * An alias match is real but WEAKER than a direct one: `S_ALIAS` is the
+         * ceiling for that field, so "Dragoon Storm" still outranks a record that
+         * only matched through a generated misspelling.
+         */
+        const aliasHit = fieldScore(term, p.aliasWords, p.aliasFlat) > 0 ? S_ALIAS : 0;
+        const best = Math.max(fieldScore(term, p.titleWords, p.titleFlat) * W_TITLE, fieldScore(term, p.detailWords, p.detailFlat) * W_DETAIL, aliasHit);
+        // AND semantics: a record missing any term is out, regardless of how well
+        // it matched the others. "red dranzer" returning everything with "dranzer"
+        // is the exact complaint that made search feel broken.
+        if (best === 0)
+            return 0;
+        total += best;
+    }
+    return total * typeWeight;
+}
+function facetsSatisfied(rec, required) {
+    if (required.length === 0)
+        return true;
+    const have = new Set(facetsOf(rec).map(([k, v]) => `${k}:${v}`));
+    return required.every((f) => have.has(f));
+}
+/**
+ * Search a prepared artifact.
+ *
+ * Returns a flat, score-ordered list. Grouping by type is the caller's job —
+ * the dropdown and the results page group differently, and a tool wants
+ * neither.
+ */
+export function searchIndex(artifact, prepared, query, opts = {}) {
+    const terms = parseSearchTxtQuery(query);
+    /*
+     * 🛑 A query that normalises to nothing returns NOTHING, never everything.
+     * "!!!" and "—" have no terms, and treating that as "no filter" is how a
+     * punctuation search returns the whole catalogue AS SEARCH RESULTS — the
+     * bug A2 fixed on /api/products, and the one `plan.empty` exists for.
+     */
+    if (terms.length === 0)
+        return [];
+    const limit = opts.limit ?? DEFAULT_LIMIT;
+    const wantTypes = new Set(opts.types ?? []);
+    const facets = opts.facets ?? [];
+    const collect = (useTerms, aliasPass) => {
+        const hits = [];
+        for (const p of prepared) {
+            const type = artifact.types[p.rec[REC_TYPE]];
+            if (!type)
+                continue;
+            if (wantTypes.size > 0 && !wantTypes.has(type.key))
+                continue;
+            if (!facetsSatisfied(p.rec, facets))
+                continue;
+            const score = recordScore(p, useTerms, type.weight);
+            if (score === 0)
+                continue;
+            hits.push({
+                typeIdx: p.rec[REC_TYPE],
+                typeKey: type.key,
+                title: p.rec[REC_TITLE],
+                detail: p.rec[REC_DETAIL],
+                href: hrefFor(artifact, p.rec),
+                facets: p.rec[REC_FACETS] ?? "",
+                // An alias hit is a weaker signal than a direct one and must not
+                // outrank it when both are present in a later, wider query.
+                score: aliasPass ? score - S_ALIAS : score,
+            });
+        }
+        return hits;
+    };
+    /*
+     * ONE pass. The alias forms live on the prepared record (see
+     * `prepareIndex`), so there is nothing to retry with — an earlier draft had
+     * a second query-expansion pass here and it was both redundant and
+     * directionally wrong.
+     */
+    const hits = collect(terms, false);
+    hits.sort((a, b) => b.score - a.score || a.title.localeCompare(b.title));
+    /*
+     * 🛑 Dedupe by DESTINATION, not by key. Two types can legitimately resolve
+     * to the same page: `model` (a composition) and `category` (the model leaf)
+     * both render `/categories/{s}`, because a composition has no page of its
+     * own. Found running the first real build — 222 model records sit on top of
+     * 1,144 categories, so a bey name could return two rows that go to the same
+     * place, which reads as a duplicate-results bug rather than as two ways of
+     * finding one thing.
+     *
+     * Keeping the HIGHER-scoring one is what preserves the value of both: the
+     * composition's name is often the longer, more specific form ("Aero Knight
+     * MS (Aero Knight Metal Sky)" against the category's "Aero Knight MS"), so
+     * whichever actually matched the query is the one worth showing.
+     *
+     * After the sort, so "first seen" is "best scoring".
+     */
+    const seen = new Set();
+    const deduped = [];
+    for (const hit of hits) {
+        if (seen.has(hit.href))
+            continue;
+        seen.add(hit.href);
+        deduped.push(hit);
+        if (deduped.length >= limit)
+            break;
+    }
+    return deduped;
+}
+/**
+ * The named primitive the tools call.
+ *
+ * 🛑 `types` is a parameter from day one BECAUSE the tools exist. `/parts`
+ * wants parts, the price index wants category leaves, the authenticity
+ * typeahead wants canonical models — three consumers, three subsets. Adding
+ * the filter later would mean changing every call site that had already been
+ * written without it.
+ *
+ * 🛑 It must NOT be wired into `/tools/authenticity`'s VERDICT path. That
+ * engine's fuzzy matching is evidence — a near-miss fires a trademark-evasion
+ * warning — and this matcher's alias corpus is built from a counterfeit
+ * seller's own spellings. Feeding one into the other would silence the warning
+ * by construction. The typeahead may propose a canonical entity; the engine
+ * must still analyse what the user actually typed. Enforced by
+ * audit-entity-resolver-consumers R2.
+ */
+export function resolveEntity(artifact, prepared, query, opts = {}) {
+    return searchIndex(artifact, prepared, query, opts);
+}

package/dist/_internal/shared/search/to-groups.d.ts

@@ -0,0 +1,52 @@
+import type { SearchEverythingResult, SearchGroup } from "../../server/features/search/search-everything";
+import type { ResolvedEntity } from "./match";
+import type { SearchIndexArtifact } from "./index-record";
+/** Rows shown per group before "see all". Matches the server tier's PER_GROUP. */
+export declare const LOCAL_PER_GROUP = 6;
+export interface ToGroupsOptions {
+    readonly perGroup?: number;
+    /**
+     * `typeKey` -> human heading. REQUIRED, and the artifact deliberately does
+     * not carry it: a label baked into a shared immutable artifact cannot be
+     * translated, and this app is `[locale]`-routed. The caller resolves it
+     * through the label system at render time.
+     */
+    readonly label: (typeKey: string) => string;
+    /** `typeKey` -> the type's browse page, from the artifact's type table. */
+    readonly moreHref: (typeKey: string) => string;
+}
+/**
+ * Group score-ordered hits by type, preserving the order the types first
+ * appear in.
+ *
+ * 🛑 Group ORDER follows the best hit in each group, not the type table's
+ * `weight`. Weight already biased the scores; applying it again as an
+ * ordering key would double-count it, and a query that matched one FAQ
+ * exactly would still rank a weak product match above it.
+ */
+export declare function toSearchGroups(hits: readonly ResolvedEntity[], opts: ToGroupsOptions): SearchGroup[];
+/** Assemble the full result envelope the page component expects. */
+export declare function toSearchResult(q: string, terms: readonly string[], hits: readonly ResolvedEntity[], opts: ToGroupsOptions): SearchEverythingResult;
+export interface FacetCount {
+    readonly key: string;
+    readonly value: string;
+    readonly count: number;
+}
+/**
+ * Count facet values across a result set.
+ *
+ * ## 🛑 This is the thing the server tier structurally cannot afford
+ *
+ * `BaseRepository.facetCounts` runs ONE aggregation query per facet value,
+ * each needing its own composite index, and on a missing index it logs and
+ * returns `undefined` so the facet "stays visible" with no count. Here it is
+ * a `reduce` over an array already in memory: zero queries, zero indexes, and
+ * a count that cannot silently fail.
+ *
+ * Counts are over the hits the CURRENT query produced, so ticking one facet
+ * and watching the others shrink is truthful rather than an approximation of
+ * the whole catalogue.
+ */
+export declare function countFacets(hits: readonly ResolvedEntity[]): FacetCount[];
+/** Look up a type's `moreHref` from the artifact's own table. */
+export declare function moreHrefResolver(artifact: Pick<SearchIndexArtifact, "types">): (typeKey: string) => string;

package/dist/_internal/shared/search/to-groups.js

@@ -0,0 +1,141 @@
+/*
+ * WHY: Tier 1 and Tier 2 must render through the SAME component, or the page
+ *      grows two layouts that drift.
+ * WHAT: `ResolvedEntity[]` (browser matcher) -> `SearchGroup[]` (the shape
+ *       `SearchResultsPageView` already renders), plus facet counting.
+ *
+ * ## 🛑 Written against the server's types, not beside them
+ *
+ * `SearchGroup` / `SearchHit` / `SearchEverythingResult` are declared in
+ * `_internal/server/features/search/search-everything.ts` and imported here
+ * as TYPES ONLY — erased at runtime, so nothing of the server reaches a
+ * browser bundle. `SearchResultsPageView` already does exactly this, so the
+ * boundary is established rather than invented here.
+ *
+ * Defining a parallel `LocalSearchGroup` would have been the easy call and
+ * the wrong one: two near-identical result shapes is how a page ends up with
+ * two renderers, and then a fix to one of them (Root Cause #59's shape).
+ *
+ * ## 🛑 `truncated` is FALSE here, and that is a real difference
+ *
+ * The server tier reads a bounded window per collection, so a saturated fetch
+ * makes its count a FLOOR and it must render "6+". Tier 1 holds the entire
+ * corpus in memory, so the count is EXACT — there is no window to saturate.
+ * Reporting `truncated: true` because a group was capped for DISPLAY would be
+ * a different claim ("there may be more we could not see") and a false one.
+ * `total` carries the real figure; `hits` is the slice shown.
+ *
+ * @tag domain:search
+ * @tag layer:shared
+ * @tag pattern:none
+ * @tag access:isomorphic
+ * @tag consumers:useSiteSearch,SearchResultsClient
+ * @tag sideEffects:none
+ */
+/** Rows shown per group before "see all". Matches the server tier's PER_GROUP. */
+export const LOCAL_PER_GROUP = 6;
+/**
+ * Group score-ordered hits by type, preserving the order the types first
+ * appear in.
+ *
+ * 🛑 Group ORDER follows the best hit in each group, not the type table's
+ * `weight`. Weight already biased the scores; applying it again as an
+ * ordering key would double-count it, and a query that matched one FAQ
+ * exactly would still rank a weak product match above it.
+ */
+export function toSearchGroups(hits, opts) {
+    const perGroup = opts.perGroup ?? LOCAL_PER_GROUP;
+    const order = [];
+    const byType = new Map();
+    for (const hit of hits) {
+        let bucket = byType.get(hit.typeKey);
+        if (!bucket) {
+            bucket = [];
+            byType.set(hit.typeKey, bucket);
+            order.push(hit.typeKey);
+        }
+        bucket.push(hit);
+    }
+    return order.map((typeKey) => {
+        const bucket = byType.get(typeKey) ?? [];
+        const groupHits = bucket.slice(0, perGroup).map((h) => ({
+            /*
+             * The href IS the identity here. The artifact has no document id — it
+             * carries a slug, and two types can share a destination (a model
+             * composition and its category leaf both render `/categories/{s}`),
+             * which the matcher already dedupes on. Using the same key keeps the
+             * two consistent; inventing `${typeKey}:${slug}` would give the same
+             * row two identities depending on which layer you asked.
+             */
+            id: h.href,
+            title: h.title,
+            href: h.href,
+            detail: h.detail || undefined,
+        }));
+        return {
+            key: typeKey,
+            label: opts.label(typeKey),
+            hits: groupHits,
+            truncated: false, // see the header — the count is exact, not a floor
+            moreHref: opts.moreHref(typeKey),
+        };
+    });
+}
+/** Assemble the full result envelope the page component expects. */
+export function toSearchResult(q, terms, hits, opts) {
+    const groups = toSearchGroups(hits, opts);
+    return {
+        q,
+        terms: [...terms],
+        groups,
+        /*
+         * The TOTAL matched, not the total shown. A page that says "24 results"
+         * and renders 12 because each group capped at 6 is lying in the direction
+         * that matters least; one that says "12" when 24 matched hides half the
+         * corpus from someone deciding whether to refine.
+         */
+        totalHits: hits.length,
+    };
+}
+/**
+ * Count facet values across a result set.
+ *
+ * ## 🛑 This is the thing the server tier structurally cannot afford
+ *
+ * `BaseRepository.facetCounts` runs ONE aggregation query per facet value,
+ * each needing its own composite index, and on a missing index it logs and
+ * returns `undefined` so the facet "stays visible" with no count. Here it is
+ * a `reduce` over an array already in memory: zero queries, zero indexes, and
+ * a count that cannot silently fail.
+ *
+ * Counts are over the hits the CURRENT query produced, so ticking one facet
+ * and watching the others shrink is truthful rather than an approximation of
+ * the whole catalogue.
+ */
+export function countFacets(hits) {
+    const tally = new Map();
+    for (const hit of hits) {
+        if (!hit.facets)
+            continue;
+        for (const pair of hit.facets.split("|")) {
+            // Guard the shape rather than trusting it: a malformed pair is one
+            // record's problem, not a reason to drop the whole rail.
+            if (pair.indexOf(":") > 0)
+                tally.set(pair, (tally.get(pair) ?? 0) + 1);
+        }
+    }
+    const out = [];
+    for (const [pair, count] of tally) {
+        const i = pair.indexOf(":");
+        out.push({ key: pair.slice(0, i), value: pair.slice(i + 1), count });
+    }
+    // Commonest first within a key, then alphabetical — a rail ordered by raw
+    // string would bury the useful refinement below the rare ones.
+    out.sort((a, b) => a.key.localeCompare(b.key) || b.count - a.count || a.value.localeCompare(b.value));
+    return out;
+}
+/** Look up a type's `moreHref` from the artifact's own table. */
+export function moreHrefResolver(artifact) {
+    const map = new Map(artifact.types.map((t) => [t.key, t.moreHref]));
+    return (typeKey) => map.get(typeKey) ?? "/";
+}

package/dist/client.d.ts

@@ -41,6 +41,8 @@ export { Tabs, TabsList, TabsTrigger, TabsContent } from "./ui/components/Tabs";
 export type { TabsProps, TabsListProps, TabsTriggerProps, TabsContentProps } from "./ui/components/Tabs";
 export { TabBarShell, TabBarButton, TabsNavSelect } from "./ui/components/TabBarShell";
 export type { TabBarShellProps, TabBarButtonProps, TabsNavSelectProps } from "./ui/components/TabBarShell";
+export { OverflowRow } from "./ui/components/OverflowRow";
+export type { OverflowRowProps, OverflowRowItem, OverflowRowDotTone, OverflowRowLinkProps } from "./ui/components/OverflowRow";
 export { SellerProductsView } from "./features/seller/components/SellerProductsView";
 export { SellerOrderDetailPanel } from "./features/seller/components/SellerOrdersView";
 export { SellerPayoutDetailContent } from "./features/seller/components/SellerPayoutsView";
@@ -264,7 +266,7 @@ export { buildEventEntryDetailFields } from "./features/events/components/event-
 export type { EntryFieldRow } from "./features/events/components/event-entry-detail-fields";
 export type { BidDetailViewer } from "./features/auctions/components/bid-detail-fields";
 export type { AuctionBidsTableProps, AuctionWithBids } from "./features/auctions/components/AuctionBidsTable";
-export { ProtectedRoute, AuthStatusPanel, ForgotPasswordView, LoginForm, RegisterForm, ResetPasswordView, VerifyEmailView } from "./features/auth/index";
+export { ProtectedRoute, ForgotPasswordView, LoginForm, RegisterForm, ResetPasswordView, VerifyEmailView } from "./features/auth/index";
 export type { AuthGuardUser, ForgotPasswordViewProps, LoginFormProps, LoginFormValues, RegisterFormProps, RegisterFormValues, ResetPasswordViewProps, VerifyEmailViewProps, } from "./features/auth/index";
 export { useLogout, useLogin, useGoogleLogin, useLinkGoogleAccount, useRegister, useForgotPassword, useResetPassword, useVerifyEmail, useChangeEmail } from "./features/auth/index";
 export type { LoginCredentials, RegisterData, ForgotPasswordData, ResetPasswordData, VerifyEmailData, ChangeEmailData } from "./features/auth/index";
@@ -284,17 +286,18 @@ export { AddressBook, AddressCard, AddressForm } from "./features/account/index"
 export type { AddressCardAddress, AddressCardProps } from "./features/account/index";
 export { useProfile, useUpdateProfile } from "./features/account/index";
 export { updateProfileSchema } from "./features/account/index";
-export { CategoryProductsView } from "./features/categories/index";
 export type { CategoryItem } from "./features/categories/index";
 export { MediaImage } from "./features/media/index";
 export { StoreSidebar } from "./features/seller/components/SellerSidebar";
 export type { StoreNavItem, StoreNavGroup } from "./features/seller/components/SellerSidebar";
 export { StoreProductsView, StoreAboutView } from "./features/stores/index";
 export type { StoreProductItem, StoreAboutViewProps, StoreDetail } from "./features/stores/index";
-export { SearchView } from "./features/search/index";
-export type { SearchViewProps } from "./features/search/index";
-export { UserSettingsView } from "./features/account/index";
-export type { UserSettingsViewProps, UserSettingsViewLabels } from "./features/account/index";
+export { useSearchIndex, ensureSearchIndex } from "./features/search/hooks/useSearchIndex";
+export { useSiteSearch } from "./features/search/hooks/useSiteSearch";
+export { useScopedSearch, mergeSearchTiers } from "./features/search/hooks/useScopedSearch";
+export type { UseScopedSearchResult } from "./features/search/hooks/useScopedSearch";
+export type { UseSiteSearchOptions, UseSiteSearchResult } from "./features/search/hooks/useSiteSearch";
+export type { SearchIndexState, SearchIndexStatus, LoadedSearchIndex, UseSearchIndexOptions, } from "./features/search/hooks/useSearchIndex";
 export { AdSlot } from "./features/homepage/components/AdSlot";
 export { useActiveAd } from "./features/homepage/hooks/useActiveAd";
 export type { ActiveAdRecord, ActiveAdCreative } from "./features/homepage/hooks/useActiveAd";
@@ -370,8 +373,8 @@ export type { SellerPayoutSettingsViewProps, SellerShippingViewProps, SellerRevi
 export { couponDraftToPayload } from "./features/seller/schemas/coupon-form";
 export type { SellerCouponPayload } from "./features/seller/schemas/coupon-form";
 export type { SellerAnalyticsSummary, SellerAnalyticsTopProduct } from "./features/seller/types/index";
-export { UserAccountHubView, UserOrdersView, UserBidsView, OrderDetailView, UserNotificationsView, UserReturnsView, UserSupportView, useNotifications } from "./features/account/index";
-export type { UserAccountHubViewProps, UserAccountHubViewLabels, UserOrdersViewProps, OrderDetailViewProps, OrderDetailViewLabels, UserNotificationsViewProps, UserNotificationsViewLabels, UserReturnsViewProps, UserSupportViewProps } from "./features/account/index";
+export { UserAccountHubView, UserOrdersView, UserBidsView, OrderDetailView, UserReturnsView, useNotifications } from "./features/account/index";
+export type { UserAccountHubViewProps, UserAccountHubViewLabels, UserOrdersViewProps, OrderDetailViewProps, OrderDetailViewLabels, UserReturnsViewProps } from "./features/account/index";
 export { useOrders, useOrder, OrdersList } from "./features/orders/index";
 export { OrderStatusTimeline } from "./features/orders/components/OrderStatusTimeline";
 export type { OrderStatusTimelineProps } from "./features/orders/components/OrderStatusTimeline";
@@ -407,7 +410,7 @@ export type { TrackArgs as TrackHistoryArgs } from "./features/history/hooks/use
 export { WISHLIST_MAX, HISTORY_MAX, CART_MAX_ITEMS, } from "./constants/limits";
 export { normalizeListingType, isAuctionListing, isPreOrderListing, isStandardListing, isPrizeDrawListing, isClassifiedListing, isDigitalCodeListing, isLiveListing, isArtListing, isStickersListing, } from "./features/products/utils/listing-type";
 export { isFinalSale, acceptsChangeOfMindReturns, } from "./features/products/constants/final-sale";
-export { isListingTypeEnabled, isCategoryTypeEnabled, enabledListingTypes, enabledCategoryTypes, ALL_LISTING_TYPES, } from "./_internal/shared/listing-types/feature-flags";
+export { isListingTypeEnabled, isCategoryTypeEnabled, enabledListingTypes, enabledCategoryTypes, ALL_LISTING_TYPES, isListingType, } from "./_internal/shared/listing-types/feature-flags";
 export { actionTracker, setActionTrackerSink, resetActionTrackerSink, type ActionEvent, type ActionTrackerSink, } from "./_internal/shared/listing-types/action-tracker";
 export { cartRequiresShipping, cartIsDigitalOnly, cartIsChatOnly, } from "./_internal/shared/listing-types/cart-shipping";
 export { ACTIONS, action, act, canPerformAction, actionsForListingType, actionLabel, type ActionDef, type ActionKind, type ActionResource, type ActionTree, type ActionConfirmation, } from "./_internal/shared/actions/action-registry";
@@ -455,6 +458,8 @@ export { SellerArtView } from "./features/seller/components/SellerArtView";
 export type { SellerArtViewProps } from "./features/seller/components/SellerArtView";
 export { SellerStickersView } from "./features/seller/components/SellerStickersView";
 export type { SellerStickersViewProps } from "./features/seller/components/SellerStickersView";
+export { SellerSparesView } from "./features/seller/components/SellerSparesView";
+export type { SellerSparesViewProps } from "./features/seller/components/SellerSparesView";
 export { SellerDigitalCodesView } from "./features/seller/components/SellerDigitalCodesView";
 export type { SellerDigitalCodesViewProps } from "./features/seller/components/SellerDigitalCodesView";
 export { SellerLiveView } from "./features/seller/components/SellerLiveView";
@@ -500,6 +505,8 @@ export type { FAQCategory, FAQCategoryItem, FAQSortOption } from "./features/faq
 export { CategoryInlineSelect } from "./features/seller/components/CategoryInlineSelect";
 export { CategoryTemplatePicker, variantForCondition } from "./features/categories/components/CategoryTemplatePicker";
 export type { CategoryTemplatePickerProps, CategoryTemplateApply } from "./features/categories/components/CategoryTemplatePicker";
+export { PriceGuidanceHint } from "./features/categories/components/PriceGuidanceHint";
+export type { PriceGuidanceHintProps } from "./features/categories/components/PriceGuidanceHint";
 export { BrandInlineSelect } from "./features/seller/components/BrandInlineSelect";
 export { API_ENDPOINTS } from "./constants/index";
 export { SELLER_LISTING_TABS, type SellerListingTabId, } from "./features/products/constants/listing-tabs";

package/dist/client.js

@@ -60,6 +60,7 @@ export { Alert } from "./ui/components/Alert.js";
 export { Divider } from "./ui/components/Divider.js";
 export { Tabs, TabsList, TabsTrigger, TabsContent } from "./ui/components/Tabs.js";
 export { TabBarShell, TabBarButton, TabsNavSelect } from "./ui/components/TabBarShell.js";
+export { OverflowRow } from "./ui/components/OverflowRow.js";
 export { SellerProductsView } from "./features/seller/components/SellerProductsView.js";
 export { SellerOrderDetailPanel } from "./features/seller/components/SellerOrdersView.js";
 export { SellerPayoutDetailContent } from "./features/seller/components/SellerPayoutsView.js";
@@ -310,7 +311,7 @@ export { buildBidDetailFields, bidStatusBadge } from "./features/auctions/compon
 // Same reason, one feature over: the entry detail modal and its full page
 // render from one builder rather than two lists that can drift.
 export { buildEventEntryDetailFields } from "./features/events/components/event-entry-detail-fields.js";
-export { ProtectedRoute, AuthStatusPanel, ForgotPasswordView, LoginForm, RegisterForm, ResetPasswordView, VerifyEmailView } from "./features/auth/index.js";
+export { ProtectedRoute, ForgotPasswordView, LoginForm, RegisterForm, ResetPasswordView, VerifyEmailView } from "./features/auth/index.js";
 export { useLogout, useLogin, useGoogleLogin, useLinkGoogleAccount, useRegister, useForgotPassword, useResetPassword, useVerifyEmail, useChangeEmail } from "./features/auth/index.js";
 export { CartView, CartItemRow, CartGroupLineRow, CartSummary, CartPriceBreakdown, CartDrawer, CheckoutView, CheckoutSuccessView, CheckoutAddressStep, useGuestCart, useCartCount, useAddToCart, useCart, useGuestCartMerge, useCartQuery } from "./features/cart/index.js";
 export { StoreAddonsPicker, hasAnyStoreAddon } from "./features/cart/index.js";
@@ -323,12 +324,19 @@ export { useAddresses, useCreateAddress, useUpdateAddress, useDeleteAddress, use
 export { AddressBook, AddressCard, AddressForm } from "./features/account/index.js";
 export { useProfile, useUpdateProfile } from "./features/account/index.js";
 export { updateProfileSchema } from "./features/account/index.js";
-export { CategoryProductsView } from "./features/categories/index.js";
 export { MediaImage } from "./features/media/index.js";
 export { StoreSidebar } from "./features/seller/components/SellerSidebar.js";
 export { StoreProductsView, StoreAboutView } from "./features/stores/index.js";
-export { SearchView } from "./features/search/index.js";
-export { UserSettingsView } from "./features/account/index.js";
+/*
+ * The browser-side search index. Exported from its DEFINING module rather
+ * than through `features/search/index` (Root Cause #18) — `ensureSearchIndex`
+ * is a module-scope singleton, and routing it through a barrel is how a
+ * second copy of that module ends up in the graph, at which point the "one
+ * fetch per page session" guarantee quietly becomes two.
+ */
+export { useSearchIndex, ensureSearchIndex } from "./features/search/hooks/useSearchIndex.js";
+export { useSiteSearch } from "./features/search/hooks/useSiteSearch.js";
+export { useScopedSearch, mergeSearchTiers } from "./features/search/hooks/useScopedSearch.js";
 export { AdSlot } from "./features/homepage/components/AdSlot.js";
 export { useActiveAd } from "./features/homepage/hooks/useActiveAd.js";
 export { registerAdSlot, registerAdSlots, unregisterAdSlot, clearAdRegistry, setAdConsentGranted, isAdConsentGranted, isAdSlotRenderable, } from "./features/homepage/ad-registry.js";
@@ -385,7 +393,7 @@ export { SellerDashboardView as StoreDashboardView, SellerDashboardView, useSell
 export { SellerPayoutSettingsView, SellerShippingView, SellerReviewsView, SellerPayoutRequestView, SellerAnalyticsStats, SellerTopProducts, SellerAnalyticsView, SellerPayoutsView, SellerCouponEditorView, SellerBidsView, SellerAddressesView, PrintCenterView, SellerOffersView, SellerGroupedListingsView, StoreGroupedListingsView, SellerAnalyticsAlertsView, StoreAnalyticsAlertsView, BarcodeField, FulfillmentView, SellerListingTypeView, SELLER_LISTING_TYPE_SPECS } from "./features/seller/components/index.js";
 /* The draft → route conversion, so both coupon callsites share one rule. */
 export { couponDraftToPayload } from "./features/seller/schemas/coupon-form.js";
-export { UserAccountHubView, UserOrdersView, UserBidsView, OrderDetailView, UserNotificationsView, UserReturnsView, UserSupportView, useNotifications } from "./features/account/index.js";
+export { UserAccountHubView, UserOrdersView, UserBidsView, OrderDetailView, UserReturnsView, useNotifications } from "./features/account/index.js";
 export { useOrders, useOrder, OrdersList } from "./features/orders/index.js";
 export { OrderStatusTimeline } from "./features/orders/components/OrderStatusTimeline.js";
 export { CountdownDisplay } from "./ui/components/CountdownDisplay.js";
@@ -415,7 +423,7 @@ export { normalizeListingType, isAuctionListing, isPreOrderListing, isStandardLi
 // `finalSale` field. See the module docstring for why `!p.finalSale` is wrong.
 export { isFinalSale, acceptsChangeOfMindReturns, } from "./features/products/constants/final-sale.js";
 // SB-UNI-X4 2026-05-13 — per-type feature-flag helpers (client-safe).
-export { isListingTypeEnabled, isCategoryTypeEnabled, enabledListingTypes, enabledCategoryTypes, ALL_LISTING_TYPES, } from "./_internal/shared/listing-types/feature-flags.js";
+export { isListingTypeEnabled, isCategoryTypeEnabled, enabledListingTypes, enabledCategoryTypes, ALL_LISTING_TYPES, isListingType, } from "./_internal/shared/listing-types/feature-flags.js";
 // SB-UNI-X5 2026-05-13 — action telemetry sink (client-safe; defaults to
 // a no-op + console.debug in dev).
 export { actionTracker, setActionTrackerSink, resetActionTrackerSink, } from "./_internal/shared/listing-types/action-tracker.js";
@@ -459,6 +467,7 @@ export { SellerBundlesView } from "./features/seller/components/SellerBundlesVie
 export { SellerClassifiedView } from "./features/seller/components/SellerClassifiedView.js";
 export { SellerArtView } from "./features/seller/components/SellerArtView.js";
 export { SellerStickersView } from "./features/seller/components/SellerStickersView.js";
+export { SellerSparesView } from "./features/seller/components/SellerSparesView.js";
 export { SellerDigitalCodesView } from "./features/seller/components/SellerDigitalCodesView.js";
 export { SellerLiveView } from "./features/seller/components/SellerLiveView.js";
 // ── Central schema registry (W1) ──────────────────────────────────────────────
@@ -495,6 +504,7 @@ export { computeCodHandlingFee } from "./_internal/shared/fees/calculator.js"; /
 export { FAQPageContent } from "./features/faq/index.js";
 export { CategoryInlineSelect } from "./features/seller/components/CategoryInlineSelect.js";
 export { CategoryTemplatePicker, variantForCondition } from "./features/categories/components/CategoryTemplatePicker.js";
+export { PriceGuidanceHint } from "./features/categories/components/PriceGuidanceHint.js";
 export { BrandInlineSelect } from "./features/seller/components/BrandInlineSelect.js";
 export { API_ENDPOINTS } from "./constants/index.js";
 // [CLIENT-SAFE] Pure, zero-import constant files — dashboard filter-tab

package/dist/configs/eslint.js

@@ -25,8 +25,28 @@
  */
 const VARIANT_CATALOGUE_RULES = [
     {
-        // Hardcoded route strings — use ROUTES.* constants.
-        selector: "Literal[value=/^\\/[a-z]+(\\?|#|$)/]",
+        /*
+         * Hardcoded route strings — use ROUTES.* constants.
+         *
+         * 🛑 The `:not(Property[key.name="route"] > Literal)` is load-bearing, not
+         * tidying. `safeRead({ route: "/products", key, fallback })` takes a route
+         * as an OBSERVABILITY LABEL — it is the string that appears on a
+         * DEGRADED_READ row, never something anything navigates to. Flagging it
+         * asked for `ROUTES.PUBLIC.PRODUCTS` in a log field.
+         *
+         * Measured 2026-10-17 across appkit/src: this rule produced 741 warnings
+         * of which 23 were real — a 97% false-positive rate. 653 were tester-case
+         * hrefs that MUST be literals (see the file-scoped exemption in the
+         * consumer's eslint.config.mjs), 43 were inside route-map.ts itself, and
+         * 22 were these labels. A rule at that ratio is not a soft gate, it is
+         * noise that teaches people to scroll past the other 23.
+         *
+         * 🛑 The combinator is DESCENDANT, not child. `>` missed
+         * `route: verifiedOnly ? "/sellers" : "/stores"`, where the literal's
+         * parent is the ConditionalExpression and not the Property — so a label
+         * behind a ternary was still flagged while the plain one beside it was not.
+         */
+        selector: 'Literal[value=/^\\/[a-z]+(\\?|#|$)/]:not(Property[key.name="route"] Literal)',
         message: "Use ROUTES.* constants from @mohasinac/appkit instead of hardcoded route strings.",
     },
     {