@mohasinac/appkit 4.41.9 → 4.41.10

package/dist/_internal/server/features/orders/adapters.js

@@ -46,7 +46,28 @@ export function orderDocumentToOrder(doc) {
     };
     const shippingCost = doc.shippingFee ?? 0;
     const discount = doc.couponDiscount ?? 0;
-    const subtotal = doc.totalPrice - shippingCost + discount;
+    /*
+     * 🛑 SUM THE ITEMS. Do not back it out of the total.
+     *
+     * This was `doc.totalPrice - shippingCost + discount`, which subtracts
+     * shipping and adds back the discount — and ignores every other charge the
+     * order carries: the platform fee, GST, the COD handling fee and deposit, and
+     * the three per-store add-ons. With shipping and discount both zero, that
+     * derivation returns the GRAND TOTAL, and the order page printed it on the
+     * row labelled "Subtotal".
+     *
+     * Measured: an order whose items are ₹1,399.00 + ₹899.00 = ₹2,298.00
+     * displayed "Subtotal ₹2,549.60 / Total ₹2,549.60" — a page that visibly does
+     * not add up, on the document a buyer checks when they think they were
+     * overcharged.
+     *
+     * The items are the authority: they are on the document, they carry their own
+     * `totalPrice`, and they cannot drift out of step with the fee list the way a
+     * subtraction must every time a fee is added. The old derivation survives only
+     * as a fallback for documents with no items.
+     */
+    const itemsSubtotal = items.reduce((sum, it) => sum + (Number(it.price) || 0) * (Number(it.quantity) || 0), 0);
+    const subtotal = items.length > 0 ? itemsSubtotal : doc.totalPrice - shippingCost + discount;
     return {
         id: doc.id,
         userId: doc.userId,

package/dist/_internal/server/jobs/core/countersReconcile.js

@@ -3,6 +3,7 @@ import { categoriesRepository, reviewRepository, storeRepository, } from "../../
 import { ProductStatusValues, PRODUCT_COLLECTION } from "../../../../features/products/schemas/firestore";
 import { CATEGORIES_COLLECTION } from "../../../../features/categories/schemas/firestore";
 import { ORDER_FIELDS, PRODUCT_FIELDS } from "../../../../constants/field-names";
+import { isListingRowAvailable } from "../../../shared/listing-types/_registry";
 import { QUERY_LIMIT } from "../handlers/messages";
 const STORES_COLLECTION = "stores";
 const ORDERS_COLLECTION = "orders";
@@ -40,6 +41,13 @@ function countRollup(t, isAuction) {
  */
 function tallyProduct(productId, data, tallies, parentsOf) {
     const isAuction = data.listingType === PRODUCT_FIELDS.LISTING_TYPE_VALUES.AUCTION;
+    /*
+     * Count only what a visitor can actually see. A published-but-sold, ended,
+     * closed or code-depleted row is excluded here for the same reason the listing
+     * excludes it — otherwise the badge promises rows the tab will not show.
+     */
+    if (!isListingRowAvailable(data, new Date()))
+        return false;
     // `category` is @deprecated in favour of `categorySlugs[]`; mirror the live
     // trigger's selection exactly so the two agree (onProductWrite.ts).
     const leaf = (Array.isArray(data.categorySlugs) && data.categorySlugs[0]) ||

package/dist/_internal/server/jobs/core/onProductWrite.js

@@ -6,6 +6,7 @@ import { normalizeError } from "../../../../errors/normalize";
 import { categoriesRepository, storeRepository, } from "../../../../repositories";
 import { ProductStatusValues } from "../../../../features/products/schemas/firestore";
 import { PRODUCT_FIELDS } from "../../../../constants/field-names";
+import { isListingRowAvailable } from "../../../shared/listing-types/_registry";
 const UNAVAILABLE_PRODUCT_STATUSES = new Set([
     ProductStatusValues.ARCHIVED,
 ]);
@@ -179,8 +180,30 @@ export async function handleProductWrite(input, ctx) {
     const afterStoreId = (after?.storeId || after?.sellerId) ?? null;
     const isAuction = after?.listingType === PRODUCT_FIELDS.LISTING_TYPE_VALUES.AUCTION;
     const beforeIsAuction = before?.listingType === PRODUCT_FIELDS.LISTING_TYPE_VALUES.AUCTION;
-    const wasPublished = beforeStatus === ProductStatusValues.PUBLISHED;
-    const isPublished = afterStatus === ProductStatusValues.PUBLISHED;
+    /*
+     * 🛑 COUNTED means published AND available, because that is what the listing
+     * shows — and therefore what the badge must promise.
+     *
+     * Counting publish/unpublish alone left the badge over-promising for as long
+     * as a row stayed published-but-sold: 36 of one run's failures were a tab
+     * badge larger than the tab it opened. `countersReconcile` now tallies the
+     * same way, and this keeps the live counter agreeing with it between nightly
+     * passes instead of drifting high all day.
+     *
+     * It closes more of the drift than it looks like it should, because the
+     * transitions that matter are all WRITES: a sale decrements stock, a refund
+     * restores it, and `auctionSettlement` writes to the product when an auction
+     * ends. A purely time-based expiry with no accompanying write is the only
+     * residue, and the nightly recount is its healer.
+     */
+    const wasCounted = beforeStatus === ProductStatusValues.PUBLISHED &&
+        !!before &&
+        isListingRowAvailable(before, new Date());
+    const isCounted = afterStatus === ProductStatusValues.PUBLISHED &&
+        !!after &&
+        isListingRowAvailable(after, new Date());
+    const wasPublished = wasCounted;
+    const isPublished = isCounted;
     const isDelete = !after;
     try {
         await dispatchProductWriteEvent({

package/dist/client.d.ts

@@ -484,6 +484,7 @@ export { SELLER_LISTING_TABS, type SellerListingTabId, } from "./features/produc
 export { ALL_TAB, EMPTY_TAB, ADMIN_PRODUCT_STATUS_TABS, ADMIN_PRODUCT_LISTING_TYPE_TABS, ADMIN_BLOG_STATUS_TABS, ADMIN_USER_STATUS_TABS, ADMIN_USER_ROLE_TABS, ADMIN_STORE_STATUS_TABS, ADMIN_PAYOUT_STATUS_TABS, ADMIN_ORDER_STATUS_TABS, ADMIN_REVIEW_STATUS_TABS, ADMIN_REVIEW_RATING_TABS, ADMIN_BID_STATUS_TABS, ADMIN_CONTACT_STATUS_TABS, ADMIN_NEWSLETTER_STATUS_TABS, ADMIN_EVENT_ENTRY_STATUS_TABS, ADMIN_EVENT_STATUS_TABS, ADMIN_CART_OWNERSHIP_TABS, ADMIN_COUPON_TYPE_TABS, SELLER_PRODUCT_STATUS_TABS, SELLER_AUCTION_STATUS_TABS, SELLER_ORDER_STATUS_TABS, SELLER_OFFER_STATUS_TABS, SELLER_BID_STATUS_TABS, } from "./features/admin/constants/filter-tabs";
 export { PRODUCT_FIELDS, PRODUCT_STATUS_TRANSITIONS, ORDER_FIELDS, REVIEW_FIELDS, BID_FIELDS, AD_FIELDS, EVENT_FIELDS, EVENT_ENTRY_FIELDS, PAYOUT_FIELDS, STORE_FIELDS, CATEGORY_FIELDS, BLOG_FIELDS, USER_FIELDS, ADDRESS_FIELDS, BRAND_FIELDS, CART_FIELDS, WISHLIST_FIELDS, HISTORY_FIELDS, NOTIFICATION_FIELDS, SESSION_FIELDS, COUPON_USAGE_FIELDS, SCAMMER_FIELDS, SUPPORT_TICKET_FIELDS, CAROUSEL_FIELDS, COUPON_FIELDS, FAQ_FIELDS, HOMEPAGE_SECTION_FIELDS, SITE_SETTINGS_FIELDS, COMMON_FIELDS, OAUTH_STATE_VALUES, SCHEMA_DEFAULTS, } from "./constants/field-names";
 export { CART_LANE, CART_LANE_PRIORITY, CART_LANE_LABELS, laneOf, activeLane, laneItems, laneCounts, isLaneCheckoutable, laneBlockReason, isLockedLane, canAddNewItems, type CartLane, type LaneAssignable, } from "./_internal/shared/checkout/lanes";
+export { getCartLineMembers, isMultiMemberLine, } from "./_internal/shared/checkout/line-members";
 export { newsletterSubscribeSchema, quickCreateTaxonomySchema, payoutMarkPaidSchema, } from "./features/admin/schemas/small-forms";
 export { raffleEntrySchema } from "./features/contact/schemas/inquiry-forms";
 export { orderCancelSchema, paymentProofSchema, } from "./features/orders/schemas/buyer-forms";

package/dist/client.js

@@ -486,6 +486,14 @@ export { PRODUCT_FIELDS, PRODUCT_STATUS_TRANSITIONS, ORDER_FIELDS, REVIEW_FIELDS
 // Checkout lanes — the derived auction > offer > standard partition of the
 // cart, and the priority rule that decides which one may be checked out.
 export { CART_LANE, CART_LANE_PRIORITY, CART_LANE_LABELS, laneOf, activeLane, laneItems, laneCounts, isLaneCheckoutable, laneBlockReason, isLockedLane, canAddNewItems, } from "./_internal/shared/checkout/lanes";
+/*
+ * The cart page needs these to tell a multi-member line from an ordinary one: a
+ * group/bundle line's `productId` is a group or category id, not a product id,
+ * so anything that resolves it as a product must skip those lines. Reading
+ * `groupMembers` directly instead would miss carts written before that field
+ * existed — the fallback lives inside these accessors.
+ */
+export { getCartLineMembers, isMultiMemberLine, } from "./_internal/shared/checkout/line-members";
 export { newsletterSubscribeSchema, quickCreateTaxonomySchema, payoutMarkPaidSchema, } from "./features/admin/schemas/small-forms";
 export { raffleEntrySchema } from "./features/contact/schemas/inquiry-forms";
 export { orderCancelSchema, paymentProofSchema, } from "./features/orders/schemas/buyer-forms";

package/dist/features/admin/components/AdminCarouselGroupEditorView.js

@@ -28,8 +28,24 @@ export function AdminCarouselGroupEditorView({ onCreated, carouselId, onSaved, .
         queryFn: () => apiClient.get(ADMIN_ENDPOINTS.CAROUSELS_BY_ID(carouselId)),
         enabled: isEdit,
     });
+    /*
+     * 🛑 `existing.data` IS the document. Do not reach for `.data.data`.
+     *
+     * `apiClient` already unwraps the envelope — it returns `data.data` — so the
+     * extra hop resolved `undefined`, the effect bailed, and the form kept its
+     * initial values: an EMPTY name and `status: "draft"`.
+     *
+     * That is not a cosmetic bug. The editor then PATCHed those defaults over a
+     * live carousel, so opening "Homepage Hero" and pressing save renamed it to
+     * "" and took it off the homepage. An editor seeded from nothing is more
+     * dangerous than one that fails to open.
+     *
+     * Mirror image of Root Cause #98, which was a raw envelope treated as the
+     * payload; this is a payload unwrapped a second time. Both typecheck, because
+     * the cast asserts the shape rather than checking it.
+     */
     React.useEffect(() => {
-        const doc = existing.data?.data;
+        const doc = existing.data;
         if (!doc)
             return;
         setName(doc.name ?? "");

package/dist/features/admin/components/AdminOrdersView.js

@@ -24,7 +24,34 @@ import { AdminOrderEditorView } from "./AdminOrderEditorView";
  * GUID) instead was Root Cause Pattern #(order-guid) — see CLAUDE.md.
  */
 function toOrderItemRows(item) {
-    const items = Array.isArray(item.items) ? item.items : [];
+    const raw = Array.isArray(item.items) ? item.items : [];
+    /*
+     * Fall back to the LEGACY flat shape when `items[]` is absent.
+     *
+     * `items[]` is canonical and every real checkout writes it, but older
+     * documents carry `productId`/`productTitle`/`quantity` at the top level
+     * instead. Reading only `items[]` rendered those rows as "Order <raw id>"
+     * beside a placeholder emoji — the product was known, just not where this
+     * looked.
+     *
+     * Root Cause #42's rule: prefer making the READER resilient over fixing only
+     * today's seed data, because the next hand-written fixture or legacy
+     * document will land in the same shape.
+     */
+    const items = raw.length > 0
+        ? raw
+        : typeof item.productTitle === "string" && item.productTitle
+            ? [
+                {
+                    productId: item.productId,
+                    productTitle: item.productTitle,
+                    quantity: item.quantity,
+                    unitPrice: item.unitPrice,
+                    totalPrice: item.totalPrice,
+                    image: item.image,
+                },
+            ]
+            : [];
     return items
         .filter((entry) => Boolean(entry) && typeof entry === "object")
         .map((entry) => ({

package/dist/features/faq/components/FAQPageContent.js

@@ -1,6 +1,6 @@
 "use client";
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { Div, Heading, Input, SlottedListingView, Text } from "../../../ui";
+import { Alert, Div, Heading, Input, SlottedListingView, Text } from "../../../ui";
 import { sortBy } from "../../../constants/sort";
 import { FAQCategorySidebar } from "./FAQCategorySidebar";
 import { FAQSortDropdown } from "./FAQSortDropdown";
@@ -14,7 +14,7 @@ export function FAQPageContent({ initialCategory = "all", categories, routeHelpe
         : sortOption === "alphabetical"
             ? "question"
             : "-createdAt";
-    const { faqs, total, isLoading } = useFaqList({
+    const { faqs, total, isLoading, isError } = useFaqList({
         category: selectedCategory === "all" ? undefined : selectedCategory,
         search: searchValue.trim() || undefined,
         sorts,
@@ -56,7 +56,20 @@ export function FAQPageContent({ initialCategory = "all", categories, routeHelpe
                                         helpful: labels.sortHelpful,
                                         newest: labels.sortNewest,
                                         alphabetical: labels.sortAlphabetical,
-                                    } })), renderTable: () => isLoading ? (_jsx(Text, { color: "muted", children: labels.loading })) : renderAccordion ? (renderAccordion(faqs)) : (_jsx(FAQAccordion, { faqs: faqs })), renderPagination: () => renderPagination?.(total) ?? null, total: total, isLoading: isLoading }), faqs.length > 0 ? (_jsx(Div, { className: "mt-12", children: _jsx(ContactCTA, { email: contact.email, phone: contact.phone, contactHref: routeHelpers.contactHref, labels: {
+                                    } })), renderTable: () => isLoading ? (_jsx(Text, { color: "muted", children: labels.loading })) : isError ? (
+                                /*
+                                 * 🛑 A failed query is NOT an empty result, and rendering it as
+                                 * one is what hid this for so long: the list query threw
+                                 * FAILED_PRECONDITION (its default -createdAt sort had no
+                                 * composite index) while the sidebar's count query, sorted
+                                 * differently, succeeded. The page therefore showed "0
+                                 * questions" beside a sidebar counting 14 matches — two numbers
+                                 * from two queries, one of which had died silently.
+                                 *
+                                 * Saying so costs nothing and makes the next index gap
+                                 * self-reporting rather than a phantom empty state.
+                                 */
+                                _jsx(Alert, { variant: "error", title: "Couldn't load questions", children: "Something went wrong fetching these FAQs. Try a different sort or reload the page." })) : renderAccordion ? (renderAccordion(faqs)) : (_jsx(FAQAccordion, { faqs: faqs })), renderPagination: () => renderPagination?.(total) ?? null, total: total, isLoading: isLoading }), faqs.length > 0 ? (_jsx(Div, { className: "mt-12", children: _jsx(ContactCTA, { email: contact.email, phone: contact.phone, contactHref: routeHelpers.contactHref, labels: {
                                         title: labels.contactTitle,
                                         description: labels.contactDescription,
                                         emailUs: labels.contactEmailUs,

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

@@ -20,12 +20,23 @@ export async function listVerifiedScammers(searchParams) {
         filters.push(sieveFilter("scamType", SIEVE_OP.EQ, String(params.scamType)));
     if (params.scamPlatform)
         filters.push(sieveFilter("scamPlatform", SIEVE_OP.EQ, String(params.scamPlatform)));
+    /*
+     * 🛑 `q` MUST reach the repository. It was read by ScamRegistryView and then
+     * dropped here, so the registry's own search box — whose subtitle reads
+     * "Search by name, phone, or UPI" — filtered nothing: `?q=zzzznope` returned
+     * every verified profile and the counter still showed the full total.
+     *
+     * Only a nonsense term exposes this, because a real term also returns rows.
+     * Same shape as the /stores SSR search that was fixed earlier: the parameter
+     * was parsed, and then simply not used.
+     */
+    const search = String(params.q ?? "").trim();
     const result = await scammerRepository.listVerified({
         filters: filters.join(",") || undefined,
         sorts: sort,
         page,
         pageSize,
-    });
+    }, search ? { search } : undefined);
     return {
         items: result.items,
         total: result.total,

package/dist/features/scams/repository/scammer.repository.d.ts

@@ -62,7 +62,24 @@ declare class ScammerRepository extends BaseRepository<ScammerDocument> {
             canSort: boolean;
         };
     };
-    listVerified(model: SieveModel): Promise<FirebaseSieveResult<ScammerDocument>>;
+    /**
+     * The PUBLIC registry at /scams.
+     *
+     * 🛑 `opts.search` is not optional decoration — the page has a prominent
+     * search box whose own subtitle says "Search by name, phone, or UPI", and it
+     * filtered nothing: `listVerifiedScammers` read `q` and never passed it on,
+     * so `?q=zzzznope` returned every verified profile and the counter still read
+     * the full total. Only a nonsense term exposes that, because a real term also
+     * returns rows.
+     *
+     * Mirrors `listAll` below deliberately, including the empty-plan guard: a
+     * search that narrows to no usable token must return NOTHING rather than the
+     * whole registry — failing open here would publish every profile to someone
+     * who searched for a single stop-word.
+     */
+    listVerified(model: SieveModel, opts?: {
+        search?: string;
+    }): Promise<FirebaseSieveResult<ScammerDocument>>;
     /** Derived on every write path via `applyWriteHooks`. */
     protected buildSearchTxtFor(data: Record<string, JsonValue>): string[] | null;
     listAll(model: SieveModel, opts?: {

package/dist/features/scams/repository/scammer.repository.js

@@ -12,13 +12,35 @@ class ScammerRepository extends BaseRepository {
     constructor() {
         super(SCAMMER_COLLECTION);
     }
-    async listVerified(model) {
-        const baseQuery = this.getCollection().where(SCAMMER_FIELDS.STATUS, "==", "verified");
-        return this.sieveQuery(model, ScammerRepository.SIEVE_FIELDS, {
+    /**
+     * The PUBLIC registry at /scams.
+     *
+     * 🛑 `opts.search` is not optional decoration — the page has a prominent
+     * search box whose own subtitle says "Search by name, phone, or UPI", and it
+     * filtered nothing: `listVerifiedScammers` read `q` and never passed it on,
+     * so `?q=zzzznope` returned every verified profile and the counter still read
+     * the full total. Only a nonsense term exposes that, because a real term also
+     * returns rows.
+     *
+     * Mirrors `listAll` below deliberately, including the empty-plan guard: a
+     * search that narrows to no usable token must return NOTHING rather than the
+     * whole registry — failing open here would publish every profile to someone
+     * who searched for a single stop-word.
+     */
+    async listVerified(model, opts) {
+        const plan = planSearchTxt(opts?.search);
+        if (plan.empty)
+            return emptySearchResult();
+        let baseQuery = this.getCollection().where(SCAMMER_FIELDS.STATUS, "==", "verified");
+        if (plan.head) {
+            baseQuery = baseQuery.where(SCAMMER_FIELDS.SEARCH_TXT, "array-contains", plan.head);
+        }
+        const result = await this.sieveQuery(model, ScammerRepository.SIEVE_FIELDS, {
             baseQuery,
             defaultPageSize: 20,
             maxPageSize: 50,
         });
+        return refineSearchTxt(result, plan.rest);
     }
     /** Derived on every write path via `applyWriteHooks`. */
     buildSearchTxtFor(data) {

package/dist/features/seller/components/SellerOrdersView.js

@@ -352,7 +352,17 @@ export function SellerOrdersView({ orderDetailApiBase = SELLER_ENDPOINTS.ORDERS,
         columns,
         mapRows: (response) => toRecordArray(response.orders).map((item, index) => {
             const itemsArr = Array.isArray(item.items) ? item.items : [];
-            const firstItem = itemsArr[0] && typeof itemsArr[0] === "object" ? itemsArr[0] : {};
+            /*
+             * Same legacy fallback as AdminOrdersView: `items[]` is canonical and
+             * every real checkout writes it, but older documents carry
+             * `productTitle` at the top level instead, and reading only `items[]`
+             * leaves the row with no title or thumbnail at all.
+             */
+            const firstItem = itemsArr[0] && typeof itemsArr[0] === "object"
+                ? itemsArr[0]
+                : typeof item.productTitle === "string" && item.productTitle
+                    ? { productTitle: item.productTitle, image: item.image }
+                    : {};
             const loc = item.physicalLocation;
             return {
                 id: toStringValue(item.id, `order-${index}`),

package/dist/features/stores/components/StoresIndexListing.js

@@ -101,11 +101,20 @@ export function StoresIndexListing({ initialData }) {
     const maxProductCount = table.get("maxProductCount");
     const featured = table.get(TABLE_KEYS.FEATURED);
     const filterParts = [];
-    if (ratingRaw) {
-        const ratings = ratingRaw.split("|").filter(Boolean);
-        if (ratings.length === 1)
-            filterParts.push(sieveFilter("averageRating", SIEVE_OP.GTE, ratings[0]));
-    }
+    /*
+     * 🛑 The rating threshold is NOT a sieve clause.
+     *
+     * It used to emit `averageRating>=N`, a field the document does not have —
+     * it nests as `stats.averageRating` — so sievejs dropped it with
+     * `throwExceptions: false` and the facet returned every store. Measured:
+     * `?rating=5` listed stores rated well below 5.
+     *
+     * Correcting the NAME would not be enough and would be worse: a GTE
+     * inequality forces Firestore to order by that field first, so pairing it
+     * with any other sort demands a composite index nobody declares (Root Cause
+     * #59). The `rating` URL param reaches the route directly and the repository
+     * refines it in memory, which composes with every sort.
+     */
     if (minProductCount)
         filterParts.push(sieveFilter("stats.totalProducts", SIEVE_OP.GTE, minProductCount));
     if (maxProductCount)
@@ -119,6 +128,7 @@ export function StoresIndexListing({ initialData }) {
         sort: table.get(TABLE_KEYS.SORT) || undefined,
         category: table.get(TABLE_KEYS.CATEGORY) || undefined,
         filters: filterParts.length > 0 ? filterParts.join(",") : undefined,
+        rating: ratingRaw || undefined,
     }, { initialData });
     const selection = useBulkSelection({ items: stores, keyExtractor: (s) => s.id ?? s.storeSlug });
     // useBottomActions must run unconditionally on every render, once per

package/dist/features/stores/components/StoresIndexPageView.d.ts

@@ -2,6 +2,21 @@ import React from "react";
 type SearchParams = Record<string, string | string[]>;
 export interface StoresIndexPageViewProps {
     searchParams?: SearchParams;
+    /**
+     * Restrict to verified stores and retitle the page. This is what /sellers is.
+     *
+     * /sellers rendered `<SellersListView />` with ZERO render props — and every
+     * slot on `SlottedListingView` is optional, so it produced a correct header,
+     * a correct breadcrumb and then a blank region: Root Cause #8 exactly. That
+     * shell had one consumer, this page, and it was empty in it.
+     *
+     * Reusing this view rather than filling in the shell means /sellers inherits
+     * what /stores already got right — the SSR `q` push-down, sandbox hiding,
+     * the ad slots and the shared listing — instead of growing a second copy that
+     * has to be fixed twice.
+     */
+    verifiedOnly?: boolean;
+    heading?: string;
 }
-export declare function StoresIndexPageView({ searchParams }: StoresIndexPageViewProps): Promise<React.JSX.Element>;
+export declare function StoresIndexPageView({ searchParams, verifiedOnly, heading, }: StoresIndexPageViewProps): Promise<React.JSX.Element>;
 export {};

package/dist/features/stores/components/StoresIndexPageView.js

@@ -5,11 +5,12 @@ import { AdSlot } from "../../homepage/components/AdSlot";
 import { StoresIndexListing } from "./StoresIndexListing";
 import { safeRead } from "../../../errors/safe-read";
 import { hidePublicTestData } from "../../../_internal/server/features/tester/visibility";
+import { STORE_FIELDS } from "../../../constants/field-names";
 function sp(params, key) {
     const v = params[key];
     return Array.isArray(v) ? v[0] ?? "" : v ?? "";
 }
-export async function StoresIndexPageView({ searchParams = {} }) {
+export async function StoresIndexPageView({ searchParams = {}, verifiedOnly = false, heading = "Stores", }) {
     const sort = sp(searchParams, "sort") || "-createdAt";
     const page = Number(sp(searchParams, "page")) || 1;
     const pageSize = Number(sp(searchParams, "pageSize")) || 24;
@@ -29,7 +30,28 @@ export async function StoresIndexPageView({ searchParams = {} }) {
      * the same filters the client would, because it never gets a second chance.
      */
     const q = sp(searchParams, "q").trim();
-    const result = await safeRead(() => storeRepository.listStores({ page, pageSize, sorts: sort }, true, q ? { search: q } : undefined), { route: "/stores", key: "stores.listStores", fallback: null });
+    /*
+     * The rating facet must be applied HERE too, not only by the client. This
+     * result is handed to <StoresIndexListing initialData=…>, and public listing
+     * hooks set staleTime: Infinity when given SSR data — so an unfiltered first
+     * paint is frozen for that query key and never self-corrects (Root Cause #30).
+     */
+    const ratingRaw = sp(searchParams, "rating");
+    const minRating = ratingRaw
+        ? Math.max(...ratingRaw.split("|").map(Number).filter((n) => Number.isFinite(n)))
+        : undefined;
+    const result = await safeRead(() => storeRepository.listStores({
+        page,
+        pageSize,
+        sorts: sort,
+        ...(verifiedOnly ? { filters: `${STORE_FIELDS.IS_VERIFIED}==true` } : {}),
+    }, true, q || minRating !== undefined
+        ? { ...(q ? { search: q } : {}), ...(minRating !== undefined ? { minRating } : {}) }
+        : undefined), {
+        route: verifiedOnly ? "/sellers" : "/stores",
+        key: "stores.listStores",
+        fallback: null,
+    });
     /*
      * The API already filters this; the SSR page called the repository directly
      * and did not, so the first paint rendered a card for `store-tester-sandbox`
@@ -38,5 +60,5 @@ export async function StoresIndexPageView({ searchParams = {} }) {
     const publicResult = result
         ? { ...result, items: hidePublicTestData(result.items) }
         : result;
-    return (_jsx(Main, { children: _jsx(Section, { padding: "y-2xl", children: _jsxs(Container, { size: "xl", children: [_jsx(Heading, { level: 1, className: "mb-8", color: "primary", size: "3xl", weight: "semibold", children: "Stores" }), _jsx(AdSlot, { id: "listing-sidebar-top", className: "mb-6" }), _jsx(StoresIndexListing, { initialData: publicResult ?? undefined }), _jsx(AdSlot, { id: "listing-sidebar-bottom", className: "mt-8" })] }) }) }));
+    return (_jsx(Main, { children: _jsx(Section, { padding: "y-2xl", children: _jsxs(Container, { size: "xl", children: [_jsx(Heading, { level: 1, className: "mb-8", color: "primary", size: "3xl", weight: "semibold", children: heading }), _jsx(AdSlot, { id: "listing-sidebar-top", className: "mb-6" }), _jsx(StoresIndexListing, { initialData: publicResult ?? undefined }), _jsx(AdSlot, { id: "listing-sidebar-bottom", className: "mt-8" })] }) }) }));
 }

package/dist/features/stores/hooks/useStores.js

@@ -15,6 +15,11 @@ export function useStores(params = {}, opts) {
         sp.set("sorts", params.sort);
     if (params.filters)
         sp.set("filters", params.filters);
+    // Rides as its own param, never inside `filters` — the route refines it in
+    // memory because a GTE inequality would force Firestore to order by rating
+    // first and break every other sort (Root Cause #59).
+    if (params.rating)
+        sp.set("rating", params.rating);
     const qs = sp.toString();
     const endpoint = opts?.endpoint ?? `${STORE_ENDPOINTS.LIST}${qs ? `?${qs}` : ""}`;
     const { data, isLoading, error, refetch } = useQuery({

package/dist/features/stores/repository/store.repository.d.ts

@@ -94,6 +94,7 @@ export declare class StoreRepository extends BaseRepository<StoreDocument> {
     protected buildSearchTxtFor(data: Record<string, JsonValue>): string[] | null;
     listStores(model: SieveModel, activeOnly?: boolean, opts?: {
         search?: string;
+        minRating?: number;
     }): Promise<FirebaseSieveResult<StoreDocument>>;
     /**
      * Admin: list all stores regardless of status.

package/dist/features/stores/repository/store.repository.js

@@ -197,6 +197,11 @@ export class StoreRepository extends BaseRepository {
             // the clause and the toggle did nothing at all. Root Cause #62's
             // EMITTED_BUT_UNFILTERABLE, live in production.
             [STORE_FIELDS.IS_FEATURED]: { canFilter: true, canSort: false },
+            // Same omission as IS_FEATURED above, found the same way: /sellers is a
+            // "Verified Sellers" page, and a filter on a field missing from this map
+            // is dropped silently by sievejs (`throwExceptions: false`) — the page
+            // would have listed every store while claiming to list verified ones.
+            [STORE_FIELDS.IS_VERIFIED]: { canFilter: true, canSort: false },
             [STORE_FIELDS.CREATED_AT]: { canFilter: false, canSort: true },
             "stats.itemsSold": { canFilter: false, canSort: true },
             "stats.averageRating": { canFilter: false, canSort: true },
@@ -225,7 +230,31 @@ export class StoreRepository extends BaseRepository {
             // WhatsApp bearer token and a list has no use for it.
             mapDoc: (snap) => this.mapDocForList(snap),
         });
-        return refineSearchTxt(result, plan.rest);
+        const searched = refineSearchTxt(result, plan.rest);
+        /*
+         * 🛑 The rating threshold is applied IN MEMORY, deliberately.
+         *
+         * The facet emitted `averageRating>=N` — a field name that does not exist
+         * (the document nests it as `stats.averageRating`), so sievejs dropped the
+         * clause with `throwExceptions: false` and the facet returned every store.
+         * Measured: `?rating=5` listed both stores, neither rated 5.
+         *
+         * Renaming it and setting `canFilter: true` would fix the drop and create a
+         * worse bug: a GTE inequality forces Firestore to order by that field
+         * first, so pairing it with any other sort demands a composite index nobody
+         * declares — the FAILED_PRECONDITION trap of Root Cause #59, and exactly
+         * what the FAQ list was doing. Trading a silent wrong answer for a silent
+         * empty one is not progress.
+         *
+         * A threshold over a small, already-paged collection is cheap to refine
+         * here, needs no index, and composes with every sort. Same shape as the
+         * availability predicate, which is a per-row test for the same reason.
+         */
+        if (opts?.minRating === undefined)
+            return searched;
+        const min = opts.minRating;
+        const kept = searched.items.filter((store) => Number(store.stats?.averageRating ?? 0) >= min);
+        return { ...searched, items: kept, total: kept.length };
     }
     /**
      * Admin: list all stores regardless of status.

package/dist/features/stores/types/index.d.ts

@@ -77,6 +77,8 @@ export interface StoreListParams {
     pageSize?: number;
     sort?: string;
     filters?: string;
+    /** Minimum average rating, pipe-joined when several chips are ticked. Refined in memory server-side. */
+    rating?: string;
 }
 export interface StoreAuctionsResponse {
     items: StoreAuctionItem[];

package/dist/features/tester/seed-data/authored/account-auth__profile-settings.js

@@ -148,8 +148,6 @@ export const authored = {
         endResult: "All three links reach the same page. Set profile visibility back to Public afterwards, since other cases read this profile as another user.",
     },
     "checklist-account-auth-profile-settings-password-change-reset-link": {
-        requiresHumanChannel: true,
-        humanChannelReason: "real email inbox",
         roles: ["buyer"],
         startPage: "/user/settings",
         steps: [

package/dist/features/tester/seed-data/authored/account-auth__signup-login.js

@@ -28,8 +28,6 @@
  */
 export const authored = {
     "checklist-account-auth-signup-login-auth-email-links-single-use": {
-        requiresHumanChannel: true,
-        humanChannelReason: "real email inbox",
         roles: ["guest"],
         startPage: "/auth/forgot-password",
         steps: [
@@ -53,8 +51,6 @@ export const authored = {
         endResult: "Account state after the second click is identical to after the first. divya.funko@gmail.com is back on TempPass123! by the final step — skipping that restore leaves the account unusable by every later case, since the seeder never resets an existing password.",
     },
     "checklist-account-auth-signup-login-auth-emails-sender-identity-and-inbox": {
-        requiresHumanChannel: true,
-        humanChannelReason: "real email inbox",
         roles: ["guest"],
         startPage: "/auth/register",
         steps: [
@@ -96,8 +92,6 @@ export const authored = {
         endResult: "Reloading /user shows 'QA Signup Tester' and the address used. The account persists — this case creates a real row that a later teardown does not remove, which is why the address is numbered rather than fixed.",
     },
     "checklist-account-auth-signup-login-email-verify": {
-        requiresHumanChannel: true,
-        humanChannelReason: "real email inbox",
         roles: ["guest"],
         startPage: "/auth/register",
         steps: [
@@ -271,8 +265,6 @@ export const authored = {
         endResult: "Navigating to /user lands on /auth/login and no data for Vivaan Kapoor is rendered at any point. A back-button press does not restore the dashboard.",
     },
     "checklist-account-auth-signup-login-password-reset": {
-        requiresHumanChannel: true,
-        humanChannelReason: "real email inbox",
         roles: ["guest"],
         startPage: "/auth/login",
         steps: [
@@ -296,8 +288,6 @@ export const authored = {
         endResult: "The password is back at TempPass123! by the final step. That restore is mandatory: the seeder never resets an existing password, so skipping it leaves this account permanently signed out of every later case.",
     },
     "checklist-account-auth-signup-login-signup-verification-email-arrives": {
-        requiresHumanChannel: true,
-        humanChannelReason: "real email inbox",
         roles: ["guest"],
         startPage: "/auth/register",
         steps: [

package/dist/features/tester/seed-data/authored/admin__site-system.js

@@ -211,8 +211,6 @@ export const authored = {
         endResult: "Read-only; send nothing.",
     },
     "checklist-admin-site-system-daily-digest-email-content": {
-        requiresHumanChannel: true,
-        humanChannelReason: "real email inbox",
         roles: ["admin"],
         startPage: "/admin/site",
         steps: [

package/dist/features/tester/seed-data/authored/buying__my-orders.js

@@ -239,8 +239,6 @@ export const authored = {
         endResult: "Read-only. If no rejected order exists, answer null rather than creating one — rejecting as fraud bans a real account for seven days.",
     },
     "checklist-buying-my-orders-order-lifecycle-emails-arrive": {
-        requiresHumanChannel: true,
-        humanChannelReason: "real email inbox",
         roles: ["buyer"],
         startPage: "/user/orders",
         steps: [

package/dist/features/tester/seed-data/authored/buying__offers.js

@@ -384,8 +384,6 @@ export const authored = {
         endResult: "All four listings keep their type-specific fields. Restore any title that was changed.",
     },
     "checklist-buying-offers-notification-email-is-a-real-email": {
-        requiresHumanChannel: true,
-        humanChannelReason: "real email inbox",
         roles: ["buyer"],
         startPage: "/user/settings",
         steps: [

package/dist/features/tester/seed-data/authored/content-discovery__notifications.js

@@ -96,8 +96,6 @@ export const authored = {
         endResult: "Read-only; nothing persists beyond the URL.",
     },
     "checklist-content-discovery-notifications-notification-email-actually-arrives": {
-        requiresHumanChannel: true,
-        humanChannelReason: "real email inbox",
         roles: ["buyer"],
         startPage: "/user/settings",
         steps: [

package/dist/features/tester/seed-data/authored/public-pages__auth-error-pages.js

@@ -36,8 +36,6 @@ export const authored = {
         endResult: "The account exists and persists. This case creates a real row that teardown does not remove, which is why the address is numbered rather than fixed.",
     },
     "checklist-public-pages-auth-error-pages-forgot-reset-password-pages": {
-        requiresHumanChannel: true,
-        humanChannelReason: "real email inbox",
         roles: ["guest"],
         startPage: "/auth/forgot-password",
         steps: [
@@ -60,8 +58,6 @@ export const authored = {
         endResult: "The password is back at TempPass123! by the final step. This case shares divya.funko@gmail.com with the single-use-link case in signup-login and with nothing else, deliberately — the seeder never resets an existing password, so a changed one outlives every future re-seed.",
     },
     "checklist-public-pages-auth-error-pages-verify-email-page": {
-        requiresHumanChannel: true,
-        humanChannelReason: "real email inbox",
         roles: ["guest"],
         startPage: "/auth/register",
         steps: [

package/dist/features/tester/seed-data/authored/selling__seller-orders.js

@@ -176,8 +176,6 @@ export const authored = {
         endResult: "Read-only; nothing persists.",
     },
     "checklist-selling-seller-orders-seller-new-order-notification-reaches-seller": {
-        requiresHumanChannel: true,
-        humanChannelReason: "real email inbox",
         roles: ["buyer", "seller"],
         startPage: "/products/product-beyblade-burst-valkyrie",
         steps: [

package/dist/seed/orders-seed-data.js

@@ -324,6 +324,30 @@ for (let i = _rawOrdersSeedData.length; i < 50; i++) {
     const qty = (i % 3) + 1;
     expandedOrders.push({
         id: generateOrderId(qty, daysBack, `${combo.userId}-${product.productId}-${i}`),
+        /*
+         * 🛑 `items[]` IS THE CANONICAL SHAPE. The flat `productId`/`productTitle`
+         * pair below is legacy and is kept only for back-compat readers.
+         *
+         * This generator emitted the flat fields alone, so 44 of the 50 seeded
+         * orders had NO `items[]` — and every order surface reads
+         * `items[0].productTitle` for its row label. The admin list therefore
+         * rendered "🧾 Order order-1-20260822-aucwon" on 22 of 25 rows: a raw id
+         * beside a placeholder emoji, for orders whose product was known all along.
+         *
+         * Same family as Root Cause #60 — a writer producing a shape no reader can
+         * render — except the writer here is the seed, which is why it survived a
+         * fix to the readers.
+         */
+        items: [
+            {
+                productId: product.productId,
+                productTitle: product.productTitle,
+                listingType: "standard",
+                quantity: qty,
+                unitPrice: product.unitPrice,
+                totalPrice: product.unitPrice * qty,
+            },
+        ],
         productId: product.productId,
         productTitle: product.productTitle,
         userId: combo.userId,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mohasinac/appkit",
-  "version": "4.41.9",
+  "version": "4.41.10",
   "license": "MIT",
   "publishConfig": {
     "access": "public"