@mohasinac/appkit 4.52.5 → 4.53.1

package/dist/features/homepage/lib/section-renderer.js

@@ -35,31 +35,55 @@ import { HomepageSectionBoundary } from "../components/HomepageSectionBoundary.j
 import { PrizeDrawsSection } from "../../products/components/PrizeDrawsSection.js";
 import { EventRafflesSection } from "../../events/components/EventRafflesSection.js";
 import { CollectionCardsSection } from "../components/CollectionCardsSection.js";
+import { HowItWorksSection } from "../components/HowItWorksSection.js";
+import { TestimonialsCarousel } from "../components/TestimonialsCarousel.js";
+import { PromoGrid } from "../components/PromoGrid.js";
 const AD_SLOT_MAP = {
     carousel: "afterHero",
     products: "afterFeaturedProducts",
     reviews: "afterReviews",
     faq: "afterFAQ",
 };
-function renderSectionElement(section, newsletterFormSlot, faqItems, slides, liveStats, sectionData, brand) {
-    const { type, config } = section;
-    switch (type) {
-        case "carousel": {
+/**
+ * One entry per `SectionType`, replacing the 25-arm `switch` this registry is
+ * carved from verbatim — every case body below is byte-identical to its
+ * switch arm, only re-homed into an object property.
+ *
+ * `Record<SectionType, SectionDef>` is EXHAUSTIVE: a `SectionType` added to
+ * the union without an entry here is a compile error, where the switch's
+ * `default: return null` let a listed-but-unhandled type render nothing with
+ * no signal anywhere. `audit-homepage-config-coverage` still passes with zero
+ * changes — it does a bare name-presence `test()` against this file as a flat
+ * string, and every config field name below is exactly where it always was.
+ */
+const SECTION_REGISTRY = {
+    carousel: {
+        surfaces: ["homepage"],
+        render: ({ config, slides }) => {
             const cfg = config;
             return (_jsx(HeroCarousel, { initialSlides: slides, title: cfg?.title, height: cfg?.height, defaultAutoplayDelayMs: cfg?.defaultAutoplayDelayMs, pauseOnHover: cfg?.pauseOnHover, showDots: cfg?.showDots, showArrows: cfg?.showArrows }));
-        }
-        case "welcome": {
+        },
+    },
+    welcome: {
+        surfaces: ["homepage"],
+        render: ({ config, brand }) => {
             const cfg = config;
             return (_jsx(WelcomeSection, { title: cleanTitle(cfg?.h1) || SECTION_TITLE.welcome, 
                 // A real `subtitle` wins; `description` is the legacy source and is
                 // still parsed for documents that only carry it.
                 subtitle: cfg?.subtitle?.trim() || parseWelcomeDescription(cfg?.description), pillLabel: cfg?.pillLabel || SECTION_COPY.welcomePill, showCTA: cfg?.showCTA ?? true, ctaLabel: cfg?.ctaText || SECTION_COPY.welcomePrimaryCta, ctaHref: cfg?.ctaLink || ROUTES.PUBLIC.PRODUCTS, secondaryCtaLabel: cfg?.secondaryCtaText || SECTION_COPY.welcomeSecondaryCta, secondaryCtaHref: cfg?.secondaryCtaLink || ROUTES.PUBLIC.PRODUCTS, trustChips: [...WELCOME_TRUST_CHIPS], brandLogoText: brand?.shortName }));
-        }
-        case "categories": {
+        },
+    },
+    categories: {
+        surfaces: ["homepage", "category", "brand"],
+        render: ({ config, sectionData }) => {
             const cfg = config;
             return (_jsx(ShopByCategorySection, { title: cleanTitle(cfg?.title) || SECTION_TITLE.categories, viewMoreHref: ROUTES.PUBLIC.CATEGORIES, viewMoreLabel: cfg?.viewMoreLabel || VIEW_MORE_LABEL.categories, initialItems: sectionData.categories, limit: cfg?.maxCategories, cta: cfg?.cta, filters: cfg?.filters, autoScroll: cfg?.autoScroll, scrollInterval: cfg?.scrollInterval, loop: cfg?.loop }));
-        }
-        case "stats": {
+        },
+    },
+    stats: {
+        surfaces: ["homepage"],
+        render: ({ config, liveStats }) => {
             const cfg = config;
             const stats = Array.isArray(cfg?.stats)
                 ? cfg.stats
@@ -85,44 +109,68 @@ function renderSectionElement(section, newsletterFormSlot, faqItems, slides, liv
             if (stats.length === 0)
                 return null;
             return _jsx(StatsCounterSection, { stats: stats, title: cleanTitle(cfg?.title) });
-        }
-        case "products": {
+        },
+    },
+    products: {
+        surfaces: ["homepage", "category", "brand", "product"],
+        render: ({ config, sectionData }) => {
             const cfg = config;
             return (_jsx(FeaturedProductsSection, { title: cleanTitle(cfg?.title) || SECTION_TITLE.products, description: cfg?.subtitle, viewMoreHref: ROUTES.PUBLIC.PRODUCTS, viewMoreLabel: cfg?.viewMoreLabel || VIEW_MORE_LABEL.products, filterByBrand: cfg?.filterByBrand, initialItems: sectionData.products, rows: cfg?.rows, 
                 // `maxProducts` is what the admin builder's "Max items" input writes;
                 // `maxItems` is the schema's own name. The two never met, so the
                 // control had no effect. Read both, newest name first.
                 maxItems: cfg?.maxItems ?? cfg?.maxProducts, autoScroll: cfg?.autoScroll, scrollInterval: cfg?.scrollInterval, loop: cfg?.loop }));
-        }
-        case "auctions": {
+        },
+    },
+    auctions: {
+        surfaces: ["homepage", "category", "brand"],
+        render: ({ config, sectionData }) => {
             const cfg = config;
             return (_jsx(FeaturedAuctionsSection, { title: cleanTitle(cfg?.title) || SECTION_TITLE.auctions, description: cfg?.subtitle, viewMoreHref: ROUTES.PUBLIC.AUCTIONS, viewMoreLabel: cfg?.viewMoreLabel || VIEW_MORE_LABEL.auctions, filterByBrand: cfg?.filterByBrand, initialItems: sectionData.auctions, rows: cfg?.rows, maxItems: cfg?.maxAuctions, autoScroll: cfg?.autoScroll, scrollInterval: cfg?.scrollInterval, loop: cfg?.loop }));
-        }
-        case "pre-orders": {
+        },
+    },
+    "pre-orders": {
+        surfaces: ["homepage", "category", "brand"],
+        render: ({ config, sectionData }) => {
             const cfg = config;
             return (_jsx(FeaturedPreOrdersSection, { title: cleanTitle(cfg?.title) || SECTION_TITLE.preOrders, description: cfg?.subtitle, viewMoreHref: ROUTES.PUBLIC.PRE_ORDERS, viewMoreLabel: cfg?.viewMoreLabel || VIEW_MORE_LABEL.preOrders, filterByBrand: cfg?.filterByBrand, initialItems: sectionData.preOrders, rows: cfg?.rows, maxItems: cfg?.maxItems, autoScroll: cfg?.autoScroll, scrollInterval: cfg?.scrollInterval, loop: cfg?.loop }));
-        }
-        case "stores": {
+        },
+    },
+    stores: {
+        surfaces: ["homepage", "category", "brand"],
+        render: ({ config, sectionData }) => {
             const cfg = config;
             return (_jsx(FeaturedStoresSection, { title: cleanTitle(cfg?.title) || SECTION_TITLE.stores, description: cfg?.subtitle, viewMoreHref: ROUTES.PUBLIC.STORES, viewMoreLabel: cfg?.viewMoreLabel || VIEW_MORE_LABEL.stores, initialItems: sectionData.stores, limit: cfg?.maxStores, autoScroll: cfg?.autoScroll, scrollInterval: cfg?.scrollInterval, loop: cfg?.loop }));
-        }
-        case "events": {
+        },
+    },
+    events: {
+        surfaces: ["homepage"],
+        render: ({ config, sectionData }) => {
             const cfg = config;
             return (_jsx(EventsSection, { title: cleanTitle(cfg?.title) || SECTION_TITLE.events, description: cfg?.subtitle, viewMoreHref: ROUTES.PUBLIC.EVENTS, viewMoreLabel: cfg?.viewMoreLabel || VIEW_MORE_LABEL.events, initialItems: sectionData.events, limit: cfg?.maxEvents, autoScroll: cfg?.autoScroll, scrollInterval: cfg?.scrollInterval, loop: cfg?.loop }));
-        }
-        case "reviews": {
+        },
+    },
+    reviews: {
+        surfaces: ["homepage", "category", "brand", "product"],
+        render: ({ config }) => {
             const cfg = config;
             return (_jsx(HomepageCustomerReviewsSection, { title: cleanTitle(cfg?.title) || SECTION_TITLE.reviews, viewMoreHref: ROUTES.PUBLIC.REVIEWS, viewMoreLabel: cfg?.viewMoreLabel || VIEW_MORE_LABEL.reviews, maxReviews: cfg?.maxReviews, itemsPerView: cfg?.itemsPerView, mobileItemsPerView: cfg?.mobileItemsPerView, autoScroll: cfg?.autoScroll, scrollInterval: cfg?.scrollInterval, loop: cfg?.loop }));
-        }
-        case "banner": {
+        },
+    },
+    banner: {
+        surfaces: ["homepage", "category", "brand", "product"],
+        render: ({ config }) => {
             const cfg = config;
             // CTAs come from the configured buttons; the component's own neutral
             // defaults fill in when none are set. Previously both labels and both
             // hrefs were hardcoded here and `buttons[]` was ignored entirely.
             const [primaryBtn, secondaryBtn] = cfg?.buttons ?? [];
             return (_jsx(CTABannerSection, { title: cfg?.content?.title || SECTION_TITLE.banner, subtitle: cfg?.content?.subtitle, description: cfg?.content?.description, height: cfg?.height, backgroundImage: cfg?.backgroundImage, primaryLabel: primaryBtn?.text, primaryHref: primaryBtn?.link, secondaryLabel: secondaryBtn?.text, secondaryHref: secondaryBtn?.link }));
-        }
-        case "trust-indicators": {
+        },
+    },
+    "trust-indicators": {
+        surfaces: ["homepage", "category", "brand"],
+        render: ({ config, brand }) => {
             const cfg = config;
             const configured = (cfg?.indicators ?? [])
                 .filter((ind) => ind?.title?.trim())
@@ -134,8 +182,11 @@ function renderSectionElement(section, newsletterFormSlot, faqItems, slides, liv
             }));
             return (_jsx(TrustFeaturesSection, { title: cleanTitle(cfg?.title) ||
                     (brand?.name ? `Why Buyers Trust ${brand.name}` : SECTION_TITLE.trustIndicators), items: configured.length > 0 ? configured : DEFAULT_TRUST_FEATURES }));
-        }
-        case "features": {
+        },
+    },
+    features: {
+        surfaces: ["homepage"],
+        render: ({ config }) => {
             const cfg = config;
             // `items` is the real shape; `features: string[]` is the legacy one and
             // becomes title-only cards. Neither reached the component before — it
@@ -146,15 +197,21 @@ function renderSectionElement(section, newsletterFormSlot, faqItems, slides, liv
                     .map((label, index) => ({ key: `feature-${index}`, title: label, description: "" })) ??
                 [];
             return (_jsx(SecurityHighlightsSection, { title: cleanTitle(cfg?.title) || SECTION_TITLE.features, pillLabel: cfg?.pillLabel || SECTION_COPY.featuresPill, items: configured.length > 0 ? configured : DEFAULT_SECURITY_ITEMS, learnMoreHref: cfg?.learnMoreLink || ROUTES.PUBLIC.SECURITY, learnMoreLabel: cfg?.learnMoreLabel || SECTION_COPY.featuresLearnMore }));
-        }
-        case "whatsapp-community": {
+        },
+    },
+    "whatsapp-community": {
+        surfaces: ["homepage"],
+        render: ({ config }) => {
             const cfg = config;
             return (_jsx(WhatsAppCommunitySection, { title: cleanTitle(cfg?.title) || SECTION_TITLE.whatsappCommunity, descriptionHtml: cfg?.description || SECTION_COPY.whatsappDescription, 
                 // No `|| 5000` fallback: inventing a member count the site cannot
                 // verify is a fabricated social-proof number.
                 memberCount: cfg?.memberCount, groupLink: cfg?.groupLink || "https://chat.whatsapp.com/", benefits: cfg?.benefits ?? [], testimonial: cfg?.testimonial, buttonText: cfg?.buttonText }));
-        }
-        case "faq": {
+        },
+    },
+    faq: {
+        surfaces: ["homepage", "category", "brand", "product"],
+        render: ({ config, faqItems }) => {
             const cfg = config;
             if (!cfg?.showOnHomepage || faqItems.length === 0)
                 return null;
@@ -177,55 +234,142 @@ function renderSectionElement(section, newsletterFormSlot, faqItems, slides, liv
             const totalFaqs = faqItems.length;
             const hasMore = totalFaqs > slicedItems.length || readSaturated;
             return (_jsx(FAQSection, { title: cleanTitle(cfg?.title) || SECTION_TITLE.faq, subtitle: cfg?.subtitle, tabs: tabs, showCategoryTabs: cfg?.showCategoryTabs ?? false, allowMultipleOpen: cfg?.allowMultipleOpen ?? false, defaultOpenCount: cfg?.defaultOpenCount ?? 0, items: slicedItems, viewMoreHref: cfg?.linkToFullPage ? ROUTES.PUBLIC.FAQS : undefined, viewMoreLabel: cfg?.viewMoreLabel || VIEW_MORE_LABEL.faq, hasMore: hasMore, moreCount: readSaturated ? 0 : totalFaqs - slicedItems.length }));
-        }
-        case "blog-articles": {
+        },
+    },
+    "blog-articles": {
+        surfaces: ["homepage", "category", "brand"],
+        render: ({ config, sectionData }) => {
             const cfg = config;
             return (_jsx(BlogArticlesSection, { title: cleanTitle(cfg?.title) || SECTION_TITLE.blogArticles, viewMoreHref: ROUTES.BLOG.LIST, viewMoreLabel: cfg?.viewMoreLabel || VIEW_MORE_LABEL.blogArticles, initialItems: sectionData.blog, limit: cfg?.maxArticles, showReadTime: cfg?.showReadTime, showAuthor: cfg?.showAuthor, showThumbnails: cfg?.showThumbnails }));
-        }
-        case "newsletter": {
+        },
+    },
+    newsletter: {
+        surfaces: ["homepage", "category", "brand"],
+        render: ({ config, newsletterFormSlot }) => {
             const cfg = config;
             return (_jsx(NewsletterSection, { title: cleanTitle(cfg?.title) || SECTION_TITLE.newsletter, subtitle: cfg?.description, privacyLabel: cfg?.privacyText, privacyHref: cfg?.privacyLink, renderForm: () => newsletterFormSlot ?? null }));
-        }
-        case "brands": {
+        },
+    },
+    brands: {
+        // Homepage-only, not category/brand: a rail of OTHER brands reads as
+        // intended cross-sell on the homepage, but on a BRAND's own detail page it
+        // would compete with that brand's reason for being there. A category page
+        // has `BrandsSection` reachable via its own tabs/grid already.
+        surfaces: ["homepage"],
+        render: ({ config, sectionData }) => {
             const cfg = config;
             return (_jsx(BrandsSection, { title: cleanTitle(cfg?.title) || SECTION_TITLE.brands, subtitle: cfg?.subtitle, limit: cfg?.maxBrands || 12, viewMoreHref: ROUTES.PUBLIC.CATEGORIES, viewMoreLabel: cfg?.viewMoreLabel || VIEW_MORE_LABEL.brands, initialItems: sectionData.brands, cta: cfg?.cta, filters: cfg?.filters, autoScroll: cfg?.autoScroll, scrollInterval: cfg?.scrollInterval, loop: cfg?.loop }));
-        }
-        case "social-feed": {
+        },
+    },
+    "social-feed": {
+        surfaces: ["homepage"],
+        render: ({ config }) => {
             const cfg = config;
             const hasStaticPosts = Array.isArray(cfg?.posts) && cfg.posts.length > 0;
             if (!cfg?.platform || (!cfg?.handle && !hasStaticPosts))
                 return null;
             return (_jsx(SocialFeedSection, { title: cleanTitle(cfg.title) || "", subtitle: cfg.subtitle, platform: cfg.platform, handle: cfg.handle ?? "", postType: cfg.postType || "all", count: cfg.count || 9, layout: cfg.layout || "grid", showCaption: cfg.showCaption ?? true, showStats: cfg.showStats ?? true, posts: cfg.posts }));
-        }
-        case "custom-cards": {
+        },
+    },
+    "custom-cards": {
+        surfaces: ["homepage", "category", "brand"],
+        render: ({ config }) => {
             const cfg = config;
             if (!cfg?.cards?.length)
                 return null;
             return (_jsx(CustomCardsSection, { title: cleanTitle(cfg.title), layout: cfg.layout ?? "grid", columns: cfg.columns ?? 3, cards: cfg.cards, autoScroll: cfg.autoScroll, scrollIntervalMs: cfg.scrollIntervalMs, loop: cfg.loop }));
-        }
-        case "google-reviews": {
+        },
+    },
+    "google-reviews": {
+        surfaces: ["homepage"],
+        render: ({ config }) => {
             const cfg = config;
             return (_jsx(GoogleReviewsSection, { placeId: cfg?.placeId ?? "", maxReviews: cfg?.maxReviews ?? 6, minRating: cfg?.minRating ?? 0, layout: cfg?.layout ?? "grid", showRating: cfg?.showRating ?? true, showDate: cfg?.showDate ?? true, linkToGoogleMaps: cfg?.linkToGoogleMaps ?? true, googleMapsUrl: cfg?.googleMapsUrl }));
-        }
-        case "featured-bundles": {
+        },
+    },
+    "featured-bundles": {
+        surfaces: ["homepage", "category", "brand"],
+        render: ({ config, sectionData }) => {
             const cfg = config;
             return (_jsx(FeaturedBundlesSection, { title: cleanTitle(cfg?.title) || SECTION_TITLE.featuredBundles, description: cfg?.subtitle, initialItems: sectionData.bundles, maxItems: cfg?.maxItems, showSavingsBadge: cfg?.showSavingsBadge, viewMoreLabel: cfg?.viewMoreLabel }));
-        }
-        case "prize-draws": {
+        },
+    },
+    "prize-draws": {
+        surfaces: ["homepage", "category", "brand"],
+        render: ({ config }) => {
             const cfg = config;
             return _jsx(PrizeDrawsSection, { config: cfg ?? {} });
-        }
-        case "event-raffles": {
+        },
+    },
+    "event-raffles": {
+        surfaces: ["homepage"],
+        render: ({ config }) => {
             const cfg = config;
             return _jsx(EventRafflesSection, { config: cfg ?? {} });
-        }
-        case "collection-cards": {
-            const cfg = config;
-            return (_jsx(CollectionCardsSection, { config: cfg ?? { collections: [] } }));
-        }
-        default:
-            return null;
-    }
+        },
+    },
+    "collection-cards": {
+        surfaces: ["homepage", "category", "brand"],
+        render: ({ config, sectionData }) => {
+            const cfg = config;
+            return (_jsx(CollectionCardsSection, { config: cfg ?? { collections: [] }, 
+                // The `categories`/`brands`/`stores` arrays homepage already fetches
+                // for ITS OWN same-named sections — zero extra round-trips. See the
+                // component's own docstring for why only these three are wired.
+                sectionData: {
+                    categories: sectionData.categories,
+                    brands: sectionData.brands,
+                    stores: sectionData.stores,
+                } }));
+        },
+    },
+    // Promoted out of the orphan-component set 2026-10-19 (see each component's
+    // own docstring for the config-serialisability fixes this required).
+    "how-it-works": {
+        surfaces: ["homepage"],
+        render: ({ config }) => {
+            const cfg = config;
+            if (!cfg?.title || !Array.isArray(cfg.steps) || cfg.steps.length === 0)
+                return null;
+            return (_jsx(HowItWorksSection, { title: cfg.title, subtitle: cfg.subtitle, pillLabel: cfg.pillLabel, ctaLabel: cfg.ctaLabel, ctaLink: cfg.ctaLink, steps: cfg.steps }));
+        },
+    },
+    testimonials: {
+        surfaces: ["homepage"],
+        render: ({ config }) => {
+            const cfg = config;
+            if (!Array.isArray(cfg?.testimonials) || cfg.testimonials.length === 0)
+                return null;
+            return (_jsx(TestimonialsCarousel, { eyebrow: cfg.eyebrow, heading: cfg.heading, testimonials: cfg.testimonials }));
+        },
+    },
+    "promo-grid": {
+        surfaces: ["homepage"],
+        render: ({ config }) => {
+            const cfg = config;
+            if (!Array.isArray(cfg?.banners) || cfg.banners.length === 0)
+                return null;
+            return (_jsx(PromoGrid, { eyebrow: cfg.eyebrow, heading: cfg.heading, banners: cfg.banners }));
+        },
+    },
+};
+function renderSectionElement(section, newsletterFormSlot, faqItems, slides, liveStats, sectionData, brand) {
+    const def = SECTION_REGISTRY[section.type];
+    // No `default` arm left to fall through to — an unmapped `SectionType` is a
+    // compile error on the registry object above, not a runtime `null`. This
+    // branch only guards a value that bypassed the type system (a raw Firestore
+    // read of a document whose `type` predates the current union).
+    if (!def)
+        return null;
+    return def.render({
+        config: section.config,
+        newsletterFormSlot,
+        faqItems,
+        slides,
+        liveStats,
+        sectionData,
+        brand,
+    });
 }
 export function renderSection(section, adSlots, newsletterFormSlot, faqItems, slides, liveStats, sectionData = {}, brand) {
     const sectionElement = renderSectionElement(section, newsletterFormSlot, faqItems, slides, liveStats, sectionData, brand);

package/dist/features/homepage/repository/homepage-sections.repository.d.ts

@@ -5,7 +5,7 @@
  */
 import type { JsonValue } from "@mohasinac/appkit";
 import { BaseRepository, type FirebaseSieveFields, type FirebaseSieveResult, type SieveModel } from "../../../providers/db-firebase";
-import { type HomepageSectionCreateInput, type HomepageSectionDocument, type SectionType } from "../schemas";
+import { type HomepageSectionCreateInput, type HomepageSectionDocument, type SectionSurface, type SectionType } from "../schemas";
 export declare class HomepageSectionsRepository extends BaseRepository<HomepageSectionDocument> {
     constructor();
     static readonly SIEVE_FIELDS: FirebaseSieveFields;
@@ -34,9 +34,41 @@ export declare class HomepageSectionsRepository extends BaseRepository<HomepageS
      * below deliberately keeps replace semantics — that is its whole purpose.
      */
     update(id: string, data: Partial<HomepageSectionDocument>): Promise<HomepageSectionDocument>;
-    getEnabledSections(): Promise<HomepageSectionDocument[]>;
+    /**
+     * Enabled sections for one surface, in `order`.
+     *
+     * 🛑 The parameter DEFAULTS to `"homepage"`, and that default is the safety
+     * property, not a convenience. This method previously returned every enabled
+     * row regardless of surface — so the moment a category-surface row exists,
+     * an unfiltered homepage would render it. Defaulting here means the existing
+     * homepage call site is correct with no change at all, and a caller that
+     * wants another surface has to say so.
+     *
+     * 🛑 The surface is matched IN MEMORY, deliberately. The only composite index
+     * on this collection is `(enabled, order)`;
+     * `where(enabled).where(surface).orderBy(order)` is a three-field composite it
+     * does not cover, and Firestore throws FAILED_PRECONDITION at RUNTIME rather
+     * than at build time. `MarketplaceHomepageView` already filters sections in
+     * memory for the listing-type gate — this follows that precedent. Section
+     * counts are tens, so the read is unchanged in cost.
+     */
+    getEnabledSections(surface?: SectionSurface): Promise<HomepageSectionDocument[]>;
     getDisabledSections(): Promise<HomepageSectionDocument[]>;
-    getSectionByType(type: SectionType): Promise<HomepageSectionDocument | null>;
+    /**
+     * 🛑 `surface` is NOT optional in spirit, even though it defaults.
+     *
+     * This was `where(type == X).limit(1)`, which assumed ONE document per type.
+     * With surfaces that assumption is false — a `products` section can exist on
+     * the homepage AND on a category page — and `limit(1)` would return whichever
+     * Firestore happened to order first. An arbitrary-but-plausible answer is the
+     * worst failure shape available here, because nothing errors.
+     *
+     * The surface is matched IN MEMORY rather than added as a second `where`: the
+     * only composite index on this collection is `(enabled, order)`, and
+     * `where(type).where(surface)` needs one that does not exist. Fetching the few
+     * rows of a type and picking by surface costs nothing at these counts.
+     */
+    getSectionByType(type: SectionType, surface?: SectionSurface): Promise<HomepageSectionDocument | null>;
     enableSection(sectionId: string): Promise<HomepageSectionDocument>;
     disableSection(sectionId: string): Promise<HomepageSectionDocument>;
     toggleSection(sectionId: string): Promise<HomepageSectionDocument>;

package/dist/features/homepage/repository/homepage-sections.repository.js

@@ -7,7 +7,7 @@ import { DatabaseError } from "../../../errors/index.js";
 import { HOMEPAGE_SECTION_FIELDS } from "../../../constants/field-names.js";
 import { BaseRepository, prepareForFirestore, parseSieveDateValue, } from "../../../providers/db-firebase/index.js";
 import { normalizeError } from "../../../errors/normalize.js";
-import { HOMEPAGE_SECTIONS_COLLECTION, createHomepageSectionId, } from "../schemas/index.js";
+import { DEFAULT_SECTION_SURFACE, HOMEPAGE_SECTIONS_COLLECTION, createHomepageSectionId, } from "../schemas/index.js";
 export class HomepageSectionsRepository extends BaseRepository {
     constructor() {
         super(HOMEPAGE_SECTIONS_COLLECTION);
@@ -16,7 +16,9 @@ export class HomepageSectionsRepository extends BaseRepository {
         return this.sieveQuery(model, HomepageSectionsRepository.SIEVE_FIELDS, { defaultPageSize: 50, maxPageSize: 200 });
     }
     async create(input) {
-        const id = createHomepageSectionId(input.type);
+        // Surface participates in the id, or a category `products` section would
+        // overwrite the homepage's — same type, same slug, one document.
+        const id = createHomepageSectionId(input.type, input.surface);
         const sectionData = {
             ...input,
             createdAt: new Date(),
@@ -68,14 +70,36 @@ export class HomepageSectionsRepository extends BaseRepository {
             },
         });
     }
-    async getEnabledSections() {
+    /**
+     * Enabled sections for one surface, in `order`.
+     *
+     * 🛑 The parameter DEFAULTS to `"homepage"`, and that default is the safety
+     * property, not a convenience. This method previously returned every enabled
+     * row regardless of surface — so the moment a category-surface row exists,
+     * an unfiltered homepage would render it. Defaulting here means the existing
+     * homepage call site is correct with no change at all, and a caller that
+     * wants another surface has to say so.
+     *
+     * 🛑 The surface is matched IN MEMORY, deliberately. The only composite index
+     * on this collection is `(enabled, order)`;
+     * `where(enabled).where(surface).orderBy(order)` is a three-field composite it
+     * does not cover, and Firestore throws FAILED_PRECONDITION at RUNTIME rather
+     * than at build time. `MarketplaceHomepageView` already filters sections in
+     * memory for the listing-type gate — this follows that precedent. Section
+     * counts are tens, so the read is unchanged in cost.
+     */
+    async getEnabledSections(surface = DEFAULT_SECTION_SURFACE) {
         try {
             const snapshot = await this.db
                 .collection(this.collection)
                 .where(HOMEPAGE_SECTION_FIELDS.ENABLED, "==", true)
                 .orderBy(HOMEPAGE_SECTION_FIELDS.ORDER, "asc")
                 .get();
-            return snapshot.docs.map((doc) => this.mapDoc(doc));
+            return snapshot.docs
+                .map((doc) => this.mapDoc(doc))
+                // Absent means "homepage" — every row written before `surface` existed
+                // was a homepage row, so this keeps all 23 of them on the homepage.
+                .filter((row) => (row.surface ?? DEFAULT_SECTION_SURFACE) === surface);
         }
         catch (error) {
             void normalizeError(error);
@@ -96,17 +120,35 @@ export class HomepageSectionsRepository extends BaseRepository {
             throw new DatabaseError(`Failed to retrieve disabled sections: ${error instanceof Error ? error.message : "Unknown error"}`);
         }
     }
-    async getSectionByType(type) {
+    /**
+     * 🛑 `surface` is NOT optional in spirit, even though it defaults.
+     *
+     * This was `where(type == X).limit(1)`, which assumed ONE document per type.
+     * With surfaces that assumption is false — a `products` section can exist on
+     * the homepage AND on a category page — and `limit(1)` would return whichever
+     * Firestore happened to order first. An arbitrary-but-plausible answer is the
+     * worst failure shape available here, because nothing errors.
+     *
+     * The surface is matched IN MEMORY rather than added as a second `where`: the
+     * only composite index on this collection is `(enabled, order)`, and
+     * `where(type).where(surface)` needs one that does not exist. Fetching the few
+     * rows of a type and picking by surface costs nothing at these counts.
+     */
+    async getSectionByType(type, surface = DEFAULT_SECTION_SURFACE) {
         try {
             const snapshot = await this.db
                 .collection(this.collection)
                 .where(HOMEPAGE_SECTION_FIELDS.TYPE, "==", type)
-                .limit(1)
                 .get();
             if (snapshot.empty)
                 return null;
-            const doc = snapshot.docs[0];
-            return this.mapDoc(doc);
+            const match = snapshot.docs.find((d) => {
+                const rowSurface = d.data().surface ?? DEFAULT_SECTION_SURFACE;
+                return rowSurface === surface;
+            });
+            if (!match)
+                return null;
+            return this.mapDoc(match);
         }
         catch (error) {
             void normalizeError(error);
@@ -219,6 +261,14 @@ export class HomepageSectionsRepository extends BaseRepository {
 HomepageSectionsRepository.SIEVE_FIELDS = {
     type: { canFilter: true, canSort: false },
     enabled: { canFilter: true, canSort: false },
+    /*
+     * 🛑 Required, not optional polish. `sieve.ts` sets
+     * `throwExceptions: false`, so a field absent from this allowlist does not
+     * raise — `findField()` returns undefined and the clause is silently
+     * DROPPED. `?filters=surface==category` would then return every section on
+     * every surface while looking like it had filtered. Root Cause #62.
+     */
+    surface: { canFilter: true, canSort: false },
     order: { canFilter: true, canSort: true },
     createdAt: { canFilter: true, canSort: true, parseValue: parseSieveDateValue },
     updatedAt: { canFilter: true, canSort: true, parseValue: parseSieveDateValue },