@mohasinac/appkit 4.53.0 → 4.53.2

package/dist/features/contact/components/ContactPageView.d.ts

@@ -1,2 +1,34 @@
 import React from "react";
-export declare function ContactPageView(): React.JSX.Element;
+/**
+ * The legal entity and support channels, passed in by the consumer page.
+ *
+ * 🛑 PROPS, not an import. This is a `"use client"` component inside appkit,
+ * so it cannot reach the consumer's `appkit.config.js` — and it must not, or
+ * appkit would carry a second definition of facts whose entire point is to
+ * have one owner (Root Cause #81). Every field is a plain string or `null`,
+ * so the whole object crosses the server/client boundary as serialisable data.
+ *
+ * Everything optional is `null` when undecided and renders a visible
+ * `[to be confirmed]` marker — never an invented support number.
+ */
+export interface ContactBusinessInfo {
+    legalName: string;
+    proprietor?: string | null;
+    structure?: string | null;
+    gstin?: string | null;
+    /** Pre-formatted lines — the consumer owns the address formatting. */
+    addressLines?: readonly string[];
+    supportEmail?: string | null;
+    supportPhone?: string | null;
+    /** Ready-to-use wa.me URL, or null. Built by the consumer so the digit-stripping rule lives in one place. */
+    whatsAppLink?: string | null;
+    whatsAppDisplay?: string | null;
+    supportHours?: string | null;
+    /** Community group invite — marketing, not support. Optional. */
+    communityUrl?: string | null;
+    grievanceHref?: string | null;
+}
+export interface ContactPageViewProps {
+    business: ContactBusinessInfo;
+}
+export declare function ContactPageView({ business }: ContactPageViewProps): React.JSX.Element;

package/dist/features/contact/components/ContactPageView.js

@@ -1,6 +1,6 @@
 "use client";
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { Container, Div, Heading, Main, Section, Stack, Text } from "../../../ui/index.js";
+import { Anchor, Container, Div, Heading, Main, PendingValue, Section, Stack, Text } from "../../../ui/index.js";
 import { AdSlot } from "../../homepage/components/AdSlot.js";
 import { ContactForm } from "./ContactForm.js";
 import { ContactInfoSidebar } from "./ContactInfoSidebar.js";
@@ -9,7 +9,53 @@ import { CONTACT_ENDPOINTS } from "../../../constants/api-endpoints.js";
 async function submitContact(data) {
     await apiClient.post(CONTACT_ENDPOINTS.SUBMIT, data);
 }
-export function ContactPageView() {
+export function ContactPageView({ business }) {
+    /*
+     * Built from `business` rather than hardcoded. Every one of these was a
+     * literal in this file until 2026-10-19 — `support@letitrip.in`,
+     * `+91 89196 65811`, `Mon-Sat · 10:00 AM - 7:00 PM IST` — which meant the
+     * contact page could disagree with `siteSettings.contact`, with the FAQ
+     * variables and with the footer, and did.
+     *
+     * A channel with no value is OMITTED rather than rendered pending: a contact
+     * sidebar listing "Email: [to be confirmed]" as a clickable row is worse
+     * than a sidebar that does not offer email. The pending markers belong on
+     * the legal-identity block below, where absence is the thing worth seeing.
+     */
+    const infoItems = [
+        business.supportEmail
+            ? {
+                icon: "📧",
+                label: "Email",
+                value: business.supportEmail,
+                href: `mailto:${business.supportEmail}`,
+            }
+            : null,
+        business.supportPhone
+            ? {
+                icon: "📞",
+                label: "Phone",
+                value: business.supportPhone,
+                href: `tel:${business.supportPhone.replace(/[^\d+]/g, "")}`,
+            }
+            : null,
+        business.whatsAppLink
+            ? {
+                icon: "💬",
+                label: "WhatsApp",
+                value: business.whatsAppDisplay ?? "Message us",
+                href: business.whatsAppLink,
+            }
+            : null,
+        business.communityUrl
+            ? {
+                icon: "👥",
+                label: "WhatsApp Community",
+                value: "Join the group",
+                href: business.communityUrl,
+            }
+            : null,
+    ].filter((i) => i !== null);
     return (_jsx(Main, { children: _jsx(Section, { padding: "y-2xl", children: _jsx(Container, { size: "xl", children: _jsxs(Stack, { gap: "section", children: [_jsxs(Stack, { gap: "3", children: [_jsx(Heading, { level: 1, size: "3xl", weight: "semibold", color: "primary", children: "Contact Us" }), _jsx(Text, { color: "muted", children: "Questions, support requests, or partnership inquiries." })] }), _jsx(AdSlot, { id: "detail-below-gallery", className: "mb-2" }), _jsxs(Div, { layout: "grid", gap: "6", className: "grid-cols-12", children: [_jsx(Div, { className: "col-span-12 lg:col-span-8", children: _jsx(ContactForm, { onSubmit: submitContact, labels: {
                                             title: "Send us a message",
                                             nameLabel: "Your Name",
@@ -17,30 +63,14 @@ export function ContactPageView() {
                                             subjectLabel: "Subject",
                                             messageLabel: "Message",
                                             submitButton: "Send Message",
-                                        } }) }), _jsx(Div, { className: "col-span-12 lg:col-span-4", children: _jsx(ContactInfoSidebar, { infoItems: [
-                                            {
-                                                icon: "📧",
-                                                label: "Email",
-                                                value: "support@letitrip.in",
-                                                href: "mailto:support@letitrip.in",
-                                            },
-                                            {
-                                                icon: "💬",
-                                                label: "WhatsApp",
-                                                value: "+91 89196 65811",
-                                                href: "https://wa.me/918919665811",
-                                            },
-                                            {
-                                                icon: "👥",
-                                                label: "WhatsApp Community",
-                                                value: "Join the group",
-                                                href: "https://chat.whatsapp.com/JOlbdSwhVWYDKujolcBZDr",
-                                            },
-                                        ], labels: {
-                                            title: "Support",
-                                            businessHoursLabel: "Business Hours",
-                                            businessHoursValue: "Mon-Sat · 10:00 AM - 7:00 PM IST",
-                                            responseTimeLabel: "Response Time",
-                                            responseTimeValue: "Usually within 24 hours",
-                                        } }) })] }), _jsx(AdSlot, { id: "detail-below-price" })] }) }) }) }));
+                                        } }) }), _jsx(Div, { className: "col-span-12 lg:col-span-4", children: _jsxs(Stack, { gap: "lg", children: [_jsx(ContactInfoSidebar, { infoItems: infoItems, labels: {
+                                                    title: "Support",
+                                                    businessHoursLabel: "Business Hours",
+                                                    // 🛑 No invented fallback. "Mon-Sat · 10:00 AM - 7:00 PM
+                                                    // IST" was hardcoded here and matched nothing anyone had
+                                                    // committed to.
+                                                    businessHoursValue: business.supportHours ?? "[to be confirmed]",
+                                                    responseTimeLabel: "Response Time",
+                                                    responseTimeValue: "Usually within 24 hours",
+                                                } }), _jsxs(Div, { surface: "muted", padding: "card", rounded: "lg", border: "default", children: [_jsx(Heading, { level: 2, size: "sm", weight: "semibold", className: "mb-3 uppercase tracking-wide", color: "muted", children: "Business details" }), _jsxs(Stack, { gap: "xs", children: [_jsx(Text, { size: "sm", weight: "medium", children: business.legalName }), business.structure ? (_jsx(Text, { size: "sm", color: "muted", children: business.structure })) : null, business.proprietor ? (_jsxs(Text, { size: "sm", color: "muted", children: ["Proprietor: ", business.proprietor] })) : null, (business.addressLines ?? []).map((line) => (_jsx(Text, { size: "sm", color: "muted", children: line }, line))), _jsxs(Text, { size: "sm", color: "muted", className: "mt-2", children: ["GSTIN:", " ", _jsx(PendingValue, { value: business.gstin, label: "GSTIN" })] }), business.grievanceHref ? (_jsx(Text, { size: "sm", className: "mt-2", children: _jsx(Anchor, { href: business.grievanceHref, children: "Grievance redressal" }) })) : null] })] })] }) })] }), _jsx(AdSlot, { id: "detail-below-price" })] }) }) }) }));
 }

package/dist/features/digital-codes/components/DigitalCodeDetailPageView.js

@@ -1,18 +1,18 @@
 import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
 import Link from "next/link.js";
 import { getDigitalCodeForDetail } from "../../../_internal/server/features/digital-code/data.js";
-const CLS_BREADCRUMB_LINK = "hover:text-primary-600 transition-colors";
+const CLS_BREADCRUMB_LINK = "hover:text-primary-600 dark:hover:text-primary-400 transition-colors";
 const CLS_DIGITALCODE_BADGE = "inline-block rounded-full bg-violet-100 dark:bg-violet-900/30 px-[var(--appkit-space-2-5)] py-[var(--appkit-space-0-5)] text-violet-700 dark:text-violet-300";
 import { ROUTES } from "../../../next/routing/route-map.js";
 import { getDefaultCurrency } from "../../../core/baseline-resolver.js";
 import { formatCurrency } from "../../../utils/number.formatter.js";
 import { normalizeRichTextHtml } from "../../../utils/string.formatter.js";
 import { safeDisplayName } from "../../../security/index.js";
-import { Div, Container, GatedPrice, Heading, Main, Nav, RichText, Row, Section, Span, Stack, Text, Dl, Dt, Dd, } from "../../../ui/index.js";
+import { Div, Container, GatedPrice, Heading, Main, Nav, RichText, Row, Section, Span, Stack, Text, SpecTable, } from "../../../ui/index.js";
 import { PreOrderDetailView } from "../../products/components/PreOrderDetailView.js";
 import { ProductGalleryClient } from "../../products/components/ProductGalleryClient.js";
 import { ProductTabsShell } from "../../products/components/ProductTabsShell.js";
-import { CustomSectionTabContent } from "../../products/components/CustomSectionTabContent.js";
+import { toCustomSectionTabs } from "../../products/components/CustomSectionTabContent.js";
 import { ShareButton } from "../../products/components/ShareButton.js";
 import { HistoryTracker } from "../../history/components/HistoryTracker.js";
 import { RelatedItemsSection } from "../../products/components/RelatedItemsSection.js";
@@ -21,6 +21,7 @@ import { GroupedListingsCarousel } from "../../grouped/components/GroupedListing
 import { getGroupsWithItemsForProduct } from "../../../_internal/server/features/grouped/data.js";
 import { ReviewsListingPanel } from "../../reviews/components/ReviewsListingPanel.js";
 import { ListingBottomActions } from "../../products/components/ListingBottomActions.js";
+import { productImageUrls } from "../../products/schemas/firestore.js";
 function toDescriptionHtml(raw) {
     if (!raw)
         return "";
@@ -41,7 +42,15 @@ export async function DigitalCodeDetailPageView({ slug, initialProduct, renderPr
     const currency = p.currency || getDefaultCurrency();
     const title = String(p.title ?? p.name ?? "Digital Code");
     const price = typeof p.price === "number" ? p.price : null;
-    const images = Array.isArray(p.images) ? p.images : typeof p.mainImage === "string" ? [p.mainImage] : [];
+    // `images` is `ProductImage[]` since A6 — `productImageUrls` is the one
+    // normaliser (it also accepts the legacy `string[]`). Casting it to
+    // `string[]` handed the gallery objects and rendered a placeholder.
+    const galleryUrls = productImageUrls(p.images);
+    const images = galleryUrls.length > 0
+        ? galleryUrls
+        : typeof p.mainImage === "string"
+            ? [p.mainImage]
+            : [];
     const meta = product.digitalCode;
     const codesLeft = meta?.codesAvailable ?? 0;
     const category = Array.isArray(p.categorySlugs) && p.categorySlugs.length > 0 ? String(p.categorySlugs[0]) : (typeof p.category === "string" ? p.category : null);
@@ -52,7 +61,6 @@ export async function DigitalCodeDetailPageView({ slug, initialProduct, renderPr
     const storeSlug = (typeof p.storeSlug === "string" ? p.storeSlug : null) || (typeof p.storeId === "string" ? p.storeId : null);
     const storeHref = storeSlug ? String(ROUTES.PUBLIC.STORE_DETAIL(storeSlug)) : null;
     const specs = Array.isArray(p.specifications) ? p.specifications : [];
-    const customSections = Array.isArray(p.customSections) ? p.customSections : [];
     const descriptionHtml = toDescriptionHtml(p.description);
     const [{ relatedItems, relatedByBrand, relatedByTags, relatedByStore }, groups, initialReviews] = await Promise.all([
         computeRelatedItems(product),
@@ -65,11 +73,7 @@ export async function DigitalCodeDetailPageView({ slug, initialProduct, renderPr
                     price: price ?? undefined,
                     storeId: typeof p.storeId === "string" ? p.storeId : undefined,
                     storeName: storeName ?? undefined,
-                } }), _jsxs(Container, { size: "xl", padding: "y-lg", children: [_jsxs(Row, { className: "mb-4", align: "center", justify: "between", gap: "sm", wrap: true, children: [_jsxs(Nav, { "aria-label": "Breadcrumb", layout: "flex-wrap", gap: "2xs", textSize: "xs", color: "muted", children: [_jsx(Link, { href: String(ROUTES.HOME), className: CLS_BREADCRUMB_LINK, children: "Home" }), _jsx(Span, { "aria-hidden": true, children: "/" }), _jsx(Link, { href: String(ROUTES.PUBLIC.DIGITAL_CODES), className: CLS_BREADCRUMB_LINK, children: "Digital Codes" }), category && (_jsxs(_Fragment, { children: [_jsx(Span, { "aria-hidden": true, children: "/" }), _jsx(Link, { href: String(ROUTES.PUBLIC.CATEGORY_DETAIL(category)), className: CLS_BREADCRUMB_LINK, children: categoryName || category })] })), _jsx(Span, { "aria-hidden": true, children: "/" }), _jsx(Span, { className: "truncate max-w-[200px]", color: "muted", children: title })] }), _jsx(ShareButton, { title: title })] }), _jsx(PreOrderDetailView, { renderGallery: () => _jsx(ProductGalleryClient, { images: images, productName: title }), renderInfo: () => (_jsxs(Stack, { gap: "md", children: [_jsxs(Div, { children: [_jsxs(Row, { gap: "xs", wrap: true, className: "mb-2", children: [_jsx(Span, { size: "xs", weight: "semibold", className: CLS_DIGITALCODE_BADGE, children: "Digital Code" }), codesLeft > 0 ? (_jsxs(Span, { size: "xs", weight: "medium", className: "inline-block", padding: "pill-sm", rounded: "full", surface: "subtle", color: "muted", children: [codesLeft, " available"] })) : (_jsx(Span, { size: "xs", weight: "semibold", className: "inline-block", padding: "pill-sm", rounded: "full", surface: "danger-surface", color: "error", children: "Sold out" }))] }), _jsx(Heading, { level: 1, className: "leading-snug", smSize: "2xl", color: "primary", size: "xl", weight: "bold", children: title })] }), price !== null && (_jsx(Text, { size: "2xl", weight: "bold", color: "primary", children: _jsx(GatedPrice, { children: formatCurrency(price, currency) }) })), meta?.redemptionInstructions && (_jsx(Text, { size: "xs", color: "muted", children: meta.redemptionInstructions })), descriptionHtml && (_jsx(RichText, { html: descriptionHtml, proseClass: "prose prose-sm max-w-none dark:prose-invert prose-p:my-0", className: "text-[length:var(--appkit-text-sm)] leading-relaxed text-[var(--appkit-color-text-muted)] line-clamp-4" })), safeSeller && (_jsx(Div, { border: "subtle", rounded: "xl", surface: "muted", padding: "md", children: _jsxs(Row, { justify: "between", align: "center", children: [_jsxs(Div, { children: [_jsx(Text, { className: "text-[10px] tracking-wide mb-0.5", color: "faint", transform: "uppercase", children: "Sold by" }), _jsx(Text, { size: "sm", weight: "semibold", color: "primary", children: safeSeller })] }), storeHref && (_jsx(Link, { href: storeHref, className: "shrink-0 rounded-lg bg-primary/10 dark:bg-primary/20 px-[var(--appkit-space-3)] py-[var(--appkit-space-1-5)] text-[length:var(--appkit-text-xs)] font-semibold text-primary-700 dark:text-primary-300 hover:bg-primary/20 dark:hover:bg-primary/30 transition-colors", children: "Visit Store \u2192" }))] }) }))] })), renderTabs: () => (_jsx(ProductTabsShell, { descriptionContent: descriptionHtml ? (_jsx(RichText, { html: descriptionHtml, proseClass: "prose prose-sm sm:prose max-w-none dark:prose-invert", className: "text-[var(--appkit-color-text-muted)]" })) : undefined, specsContent: specs.length > 0 ? (_jsx(Dl, { divide: "subtle", rounded: "xl", border: "subtle", className: "overflow-hidden", children: specs.map((s, i) => (_jsxs(Row, { gap: "md", oddEven: "zebra", surface: "default", padding: "inline", children: [_jsx(Dt, { className: "w-36 flex-shrink-0", color: "primary", weight: "medium", children: s.name }), _jsxs(Dd, { className: "flex-1", color: "muted", children: [s.value, s.unit ? ` ${s.unit}` : ""] })] }, i))) })) : undefined, reviewsContent: _jsx(ReviewsListingPanel, { source: { kind: "product", productId: product.id }, stateMode: "local", context: "listing", initialData: initialReviews, emptyLabel: "No reviews yet \u2014 be the first to review this product." }), customTabs: customSections.map((s) => ({
-                                id: s.id,
-                                label: s.title,
-                                content: _jsx(CustomSectionTabContent, { section: s }),
-                            })) })), renderBuyBar: () => (_jsx(Div, { id: "digital-code-buy-bar", children: renderPrimaryActions?.({
+                } }), _jsxs(Container, { size: "xl", padding: "y-lg", children: [_jsxs(Row, { className: "mb-4", align: "center", justify: "between", gap: "sm", wrap: true, children: [_jsxs(Nav, { "aria-label": "Breadcrumb", layout: "flex-wrap", gap: "2xs", textSize: "xs", color: "muted", children: [_jsx(Link, { href: String(ROUTES.HOME), className: CLS_BREADCRUMB_LINK, children: "Home" }), _jsx(Span, { "aria-hidden": true, children: "/" }), _jsx(Link, { href: String(ROUTES.PUBLIC.DIGITAL_CODES), className: CLS_BREADCRUMB_LINK, children: "Digital Codes" }), category && (_jsxs(_Fragment, { children: [_jsx(Span, { "aria-hidden": true, children: "/" }), _jsx(Link, { href: String(ROUTES.PUBLIC.CATEGORY_DETAIL(category)), className: CLS_BREADCRUMB_LINK, children: categoryName || category })] })), _jsx(Span, { "aria-hidden": true, children: "/" }), _jsx(Span, { className: "truncate max-w-[200px]", color: "muted", children: title })] }), _jsx(ShareButton, { title: title })] }), _jsx(PreOrderDetailView, { renderGallery: () => _jsx(ProductGalleryClient, { images: images, productName: title }), renderInfo: () => (_jsxs(Stack, { gap: "md", children: [_jsxs(Div, { children: [_jsxs(Row, { gap: "xs", wrap: true, className: "mb-2", children: [_jsx(Span, { size: "xs", weight: "semibold", className: CLS_DIGITALCODE_BADGE, children: "Digital Code" }), codesLeft > 0 ? (_jsxs(Span, { size: "xs", weight: "medium", className: "inline-block", padding: "pill-sm", rounded: "full", surface: "subtle", color: "muted", children: [codesLeft, " available"] })) : (_jsx(Span, { size: "xs", weight: "semibold", className: "inline-block", padding: "pill-sm", rounded: "full", surface: "danger-surface", color: "error", children: "Sold out" }))] }), _jsx(Heading, { level: 1, className: "leading-snug", smSize: "2xl", color: "primary", size: "xl", weight: "bold", children: title })] }), price !== null && (_jsx(Text, { size: "2xl", weight: "bold", color: "primary", children: _jsx(GatedPrice, { children: formatCurrency(price, currency) }) })), meta?.redemptionInstructions && (_jsx(Text, { size: "xs", color: "muted", children: meta.redemptionInstructions })), descriptionHtml && (_jsx(RichText, { html: descriptionHtml, proseClass: "prose prose-sm max-w-none dark:prose-invert prose-p:my-0", className: "text-[length:var(--appkit-text-sm)] leading-relaxed text-[var(--appkit-color-text-muted)] line-clamp-4" })), safeSeller && (_jsx(Div, { border: "subtle", rounded: "xl", surface: "muted", padding: "md", children: _jsxs(Row, { justify: "between", align: "center", children: [_jsxs(Div, { children: [_jsx(Text, { className: "text-[10px] tracking-wide mb-0.5", color: "faint", transform: "uppercase", children: "Sold by" }), _jsx(Text, { size: "sm", weight: "semibold", color: "primary", children: safeSeller })] }), storeHref && (_jsx(Link, { href: storeHref, className: "shrink-0 rounded-lg bg-primary/10 dark:bg-primary/20 px-[var(--appkit-space-3)] py-[var(--appkit-space-1-5)] text-[length:var(--appkit-text-xs)] font-semibold text-primary-700 dark:text-primary-300 hover:bg-primary/20 dark:hover:bg-primary/30 transition-colors", children: "Visit Store \u2192" }))] }) }))] })), renderTabs: () => (_jsx(ProductTabsShell, { descriptionContent: descriptionHtml ? (_jsx(RichText, { html: descriptionHtml, proseClass: "prose prose-sm sm:prose max-w-none dark:prose-invert", className: "text-[var(--appkit-color-text-muted)]" })) : undefined, specsContent: specs.length > 0 ? (_jsx(SpecTable, { rows: specs })) : undefined, reviewsContent: _jsx(ReviewsListingPanel, { source: { kind: "product", productId: product.id }, stateMode: "local", context: "listing", initialData: initialReviews, emptyLabel: "No reviews yet \u2014 be the first to review this product." }), customTabs: toCustomSectionTabs(p.customSections) })), renderBuyBar: () => (_jsx(Div, { id: "digital-code-buy-bar", children: renderPrimaryActions?.({
                                 productId: String(product.id),
                                 productSlug: String(p.slug ?? product.id),
                                 productTitle: title,

package/dist/features/grouped/components/GroupedListingDetailView.js

@@ -3,6 +3,7 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { Container, Div, Heading, Section, Span, Stack, Text, } from "../../../ui/index.js";
 import { MediaImage } from "../../media/MediaImage.js";
 import { GroupMemberPicker } from "../../products/components/GroupMemberPicker.js";
+import { readGroupRules } from "../../../_internal/shared/features/products/group-rules.js";
 const __O = { hidden: "overflow-hidden" };
 /** Human label per theme — mirrors GROUP_THEME_TITLE on the carousel. */
 const THEME_LABEL = {
@@ -13,5 +14,12 @@ const THEME_LABEL = {
     generic: "Grouped listing",
 };
 export function GroupedListingDetailView({ group, members }) {
-    return (_jsx(Section, { padding: "section", children: _jsx(Container, { children: _jsxs(Stack, { gap: "comfortable", children: [group.coverImage && (_jsx(Div, { className: `relative h-48 w-full md:h-64 ${__O.hidden}`, rounded: "xl", surface: "muted", children: _jsx(MediaImage, { src: group.coverImage, alt: group.title, size: "banner" }) })), _jsxs(Stack, { gap: "xs", children: [_jsx(Span, { size: "xs", color: "muted", transform: "uppercase", weight: "semibold", children: THEME_LABEL[group.groupTheme] }), _jsx(Heading, { level: 1, children: group.title }), group.description && (_jsx(Text, { color: "muted", children: group.description })), _jsxs(Text, { size: "sm", color: "muted", children: [members.length, " item", members.length === 1 ? "" : "s", " in this group"] })] }), members.length > 0 ? (_jsxs(Stack, { gap: "sm", children: [_jsx(Heading, { level: 2, size: "lg", children: "Pick what you want" }), _jsx(Text, { size: "sm", color: "muted", children: "Choose a quantity for each item \u2014 they'll go into your cart as a single line you can edit later." }), _jsx(GroupMemberPicker, { groupId: group.id, groupSource: "grouped-listing", members: members })] })) : (_jsx(Text, { color: "muted", children: "Nothing in this group is available right now." }))] }) }) }));
+    return (_jsx(Section, { padding: "section", children: _jsx(Container, { children: _jsxs(Stack, { gap: "comfortable", children: [group.coverImage && (_jsx(Div, { className: `relative h-48 w-full md:h-64 ${__O.hidden}`, rounded: "xl", surface: "muted", children: _jsx(MediaImage, { src: group.coverImage, alt: group.title, size: "banner" }) })), _jsxs(Stack, { gap: "xs", children: [_jsx(Span, { size: "xs", color: "muted", transform: "uppercase", weight: "semibold", children: THEME_LABEL[group.groupTheme] }), _jsx(Heading, { level: 1, children: group.title }), group.description && (_jsx(Text, { color: "muted", children: group.description })), _jsxs(Text, { size: "sm", color: "muted", children: [members.length, " item", members.length === 1 ? "" : "s", " in this group"] })] }), members.length > 0 ? (_jsxs(Stack, { gap: "sm", children: [_jsx(Heading, { level: 2, size: "lg", children: "Pick what you want" }), _jsx(Text, { size: "sm", color: "muted", children: "Choose a quantity for each item \u2014 they'll go into your cart as a single line you can edit later." }), _jsx(GroupMemberPicker, { groupId: group.id, groupSource: "grouped-listing", members: members, 
+                                /*
+                                 * Off the group document this view already loaded. The picker
+                                 * and `addGroupLineToCart` run the SAME `checkGroupRules`, so
+                                 * passing them here only changes WHEN the buyer learns a
+                                 * selection is invalid — not whether it is refused.
+                                 */
+                                rules: readGroupRules(group) })] })) : (_jsx(Text, { color: "muted", children: "Nothing in this group is available right now." }))] }) }) }));
 }

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

@@ -39,6 +39,11 @@ export interface GroupedListingDocument extends BaseDocument {
     /** Computed from activeMemberCount < minActiveMembers. */
     visibilityStatus: GroupVisibility;
     isActive: boolean;
+    groupMinMembers?: number;
+    groupMaxMembers?: number;
+    groupMaxUnitsPerMember?: number;
+    groupRequiredMemberIds?: string[];
+    groupDiscountPercent?: number;
     isFeatured: boolean;
     storeId?: string;
     brandSlug?: string;

package/dist/features/homepage/actions/homepage-section-actions.d.ts

@@ -2,17 +2,17 @@ import { z } from "zod";
 import type { HomepageSectionDocument } from "../schemas";
 import type { FirebaseSieveResult } from "../../../providers/db-firebase";
 export declare const createSectionSchema: z.ZodObject<{
-    type: z.ZodEnum<["welcome", "carousel", "stats", "trust-indicators", "categories", "brands", "products", "pre-orders", "auctions", "banner", "features", "reviews", "whatsapp-community", "faq", "blog-articles", "newsletter", "stores", "events", "social-feed", "custom-cards", "google-reviews", "featured-bundles", "prize-draws", "event-raffles", "collection-cards"]>;
+    type: z.ZodEnum<[import("../schemas").SectionType, ...import("../schemas").SectionType[]]>;
     enabled: z.ZodDefault<z.ZodBoolean>;
     order: z.ZodDefault<z.ZodNumber>;
     config: z.ZodOptional<z.ZodObject<{}, "passthrough", z.ZodTypeAny, z.objectOutputType<{}, z.ZodTypeAny, "passthrough">, z.objectInputType<{}, z.ZodTypeAny, "passthrough">>>;
 }, "strip", z.ZodTypeAny, {
-    type: "banner" | "stores" | "products" | "pre-orders" | "prize-draws" | "auctions" | "reviews" | "events" | "categories" | "brands" | "carousel" | "newsletter" | "features" | "stats" | "welcome" | "trust-indicators" | "whatsapp-community" | "faq" | "blog-articles" | "social-feed" | "custom-cards" | "google-reviews" | "featured-bundles" | "event-raffles" | "collection-cards";
+    type: import("../schemas").SectionType;
     enabled: boolean;
     order: number;
     config?: z.objectOutputType<{}, z.ZodTypeAny, "passthrough"> | undefined;
 }, {
-    type: "banner" | "stores" | "products" | "pre-orders" | "prize-draws" | "auctions" | "reviews" | "events" | "categories" | "brands" | "carousel" | "newsletter" | "features" | "stats" | "welcome" | "trust-indicators" | "whatsapp-community" | "faq" | "blog-articles" | "social-feed" | "custom-cards" | "google-reviews" | "featured-bundles" | "event-raffles" | "collection-cards";
+    type: import("../schemas").SectionType;
     enabled?: boolean | undefined;
     order?: number | undefined;
     config?: z.objectInputType<{}, z.ZodTypeAny, "passthrough"> | undefined;

package/dist/features/homepage/components/CollectionCardsSection.d.ts

@@ -1,13 +1,35 @@
 import type { CollectionCardsSectionConfig } from "../schemas/firestore";
+import type { CategoryItem } from "../../categories/types";
+import type { StoreListItem } from "../../stores/types";
 export interface CollectionCardsSectionProps {
     config: CollectionCardsSectionConfig;
+    /**
+     * Pre-fetched items for the entry types that are actually wired — see the
+     * module docstring below for which ones and why those three specifically.
+     */
+    sectionData?: {
+        categories?: CategoryItem[];
+        brands?: CategoryItem[];
+        stores?: StoreListItem[];
+    };
 }
 /**
- * Renders a single homepage strip that mixes multiple resource types (products,
- * stores, blog, etc.) — driven entirely from config.
+ * Renders a single homepage strip that mixes multiple resource types
+ * (products, stores, blog, etc.), driven entirely from config.
  *
- * Each entry's data fetch wires into the existing per-resource repositories.
- * Until the data wiring lands the section renders the configured collection
- * tabs + a placeholder, exercising the schema/admin plumbing end-to-end.
+ * 🛑 `categories` / `brands` / `stores` entries render REAL data as of
+ * 2026-10-19 — reusing `sectionData` that `MarketplaceHomepageView` already
+ * fetches for the dedicated `categories`/`brands`/`stores` sections, so this
+ * costs zero extra round-trips (Rule #6). Those three were chosen first
+ * because they are the PERMANENT axes: populated independently of the
+ * product catalogue's size, so a `collection-cards` section built from them
+ * can never go empty the way a `"products"`/`"auctions"` entry could.
+ *
+ * Every other entry type (`products`, `auctions`, `pre-orders`, `events`,
+ * `blog-posts`, `reviews`) still renders the honest placeholder — a real
+ * "not wired yet" state is correct here, not a bug to paper over with
+ * fabricated data, and the earlier revision's "data wiring lands with the
+ * bundle/raffle work" message survives per-entry rather than as a blanket
+ * claim about the whole section.
  */
-export declare function CollectionCardsSection({ config, }: CollectionCardsSectionProps): Promise<import("react").JSX.Element | null>;
+export declare function CollectionCardsSection({ config, sectionData, }: CollectionCardsSectionProps): Promise<import("react").JSX.Element | null>;

package/dist/features/homepage/components/CollectionCardsSection.js

@@ -1,6 +1,8 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import Link from "next/link.js";
-import { Container, Heading, Row, Section, Span, Stack, Text, } from "../../../ui/index.js";
+import { Container, Div, Grid, Heading, Row, Section, Span, Stack, Text, } from "../../../ui/index.js";
+import { MediaImage } from "../../media/MediaImage.js";
+import { ROUTES } from "../../../next/routing/route-map.js";
 const DEFAULT_ITEMS_PER_ROW = 4;
 const DEFAULT_MAX_ITEMS = 12;
 function entryLabel(entry) {
@@ -19,14 +21,25 @@ function entryLabel(entry) {
     }
 }
 /**
- * Renders a single homepage strip that mixes multiple resource types (products,
- * stores, blog, etc.) — driven entirely from config.
+ * Renders a single homepage strip that mixes multiple resource types
+ * (products, stores, blog, etc.), driven entirely from config.
  *
- * Each entry's data fetch wires into the existing per-resource repositories.
- * Until the data wiring lands the section renders the configured collection
- * tabs + a placeholder, exercising the schema/admin plumbing end-to-end.
+ * 🛑 `categories` / `brands` / `stores` entries render REAL data as of
+ * 2026-10-19 — reusing `sectionData` that `MarketplaceHomepageView` already
+ * fetches for the dedicated `categories`/`brands`/`stores` sections, so this
+ * costs zero extra round-trips (Rule #6). Those three were chosen first
+ * because they are the PERMANENT axes: populated independently of the
+ * product catalogue's size, so a `collection-cards` section built from them
+ * can never go empty the way a `"products"`/`"auctions"` entry could.
+ *
+ * Every other entry type (`products`, `auctions`, `pre-orders`, `events`,
+ * `blog-posts`, `reviews`) still renders the honest placeholder — a real
+ * "not wired yet" state is correct here, not a bug to paper over with
+ * fabricated data, and the earlier revision's "data wiring lands with the
+ * bundle/raffle work" message survives per-entry rather than as a blanket
+ * claim about the whole section.
  */
-export async function CollectionCardsSection({ config, }) {
+export async function CollectionCardsSection({ config, sectionData, }) {
     const title = config.title ?? "Featured Collections";
     const subtitle = config.subtitle;
     const collections = Array.isArray(config.collections) ? config.collections : [];
@@ -37,5 +50,27 @@ export async function CollectionCardsSection({ config, }) {
     if (collections.length === 0) {
         return null;
     }
-    return (_jsx(Section, { padding: "y-2xl", children: _jsx(Container, { size: "xl", children: _jsxs(Stack, { gap: "md", children: [_jsxs(Stack, { gap: "xs", children: [_jsx(Heading, { level: 2, size: "2xl", weight: "semibold", color: "primary", children: title }), subtitle ? (_jsx(Text, { size: "sm", color: "muted", children: subtitle })) : null] }), showTabs ? (_jsx(Row, { gap: "sm", wrap: true, children: collections.slice(0, 3).map((entry, idx) => (_jsx(Span, { border: "default", padding: "x-sm", className: "py-[0.25rem]", rounded: "full", color: "muted", size: "xs", weight: "medium", children: entryLabel(entry) }, `${entry.type}-${idx}`))) })) : null, _jsxs(Stack, { align: "start", gap: "sm", className: "border-dashed text-left", border: "strong", paddingY: "y-3xl", paddingX: "x-lg", rounded: "2xl", children: [_jsxs(Text, { size: "sm", color: "muted", children: ["Mixed collection rendering (", collections.length, "/3 collection", collections.length === 1 ? "" : "s", ", up to ", maxItems, " items,", " ", itemsPerRow, " per row) \u2014 data wiring lands with the bundle/raffle work."] }), cta ? (_jsxs(Link, { href: cta.href, className: "text-[length:var(--appkit-text-sm)] font-medium text-primary hover:underline", children: [cta.label, " \u2192"] })) : null] })] }) }) }));
+    const wiredEntries = collections.filter((e) => e.type === "categories" || e.type === "brands" || e.type === "stores");
+    const unwiredEntries = collections.filter((e) => e.type !== "categories" && e.type !== "brands" && e.type !== "stores");
+    return (_jsx(Section, { padding: "y-2xl", children: _jsx(Container, { size: "xl", children: _jsxs(Stack, { gap: "md", children: [_jsxs(Stack, { gap: "xs", children: [_jsx(Heading, { level: 2, size: "2xl", weight: "semibold", color: "primary", children: title }), subtitle ? (_jsx(Text, { size: "sm", color: "muted", children: subtitle })) : null] }), showTabs ? (_jsx(Row, { gap: "sm", wrap: true, children: collections.slice(0, 3).map((entry, idx) => (_jsx(Span, { border: "default", padding: "x-sm", className: "py-[0.25rem]", rounded: "full", color: "muted", size: "xs", weight: "medium", children: entryLabel(entry) }, `${entry.type}-${idx}`))) })) : null, wiredEntries.map((entry, idx) => {
+                        const rows = entry.type === "categories"
+                            ? (sectionData?.categories ?? [])
+                                .slice(0, entry.limit ?? maxItems)
+                                .map((c) => ({ slug: c.slug, name: c.name, image: c.display?.coverImage }))
+                            : entry.type === "brands"
+                                ? (sectionData?.brands ?? [])
+                                    .slice(0, entry.limit ?? maxItems)
+                                    .map((b) => ({ slug: b.slug, name: b.name, image: b.display?.coverImage }))
+                                : (sectionData?.stores ?? [])
+                                    .slice(0, entry.limit ?? maxItems)
+                                    .map((s) => ({ slug: s.storeSlug, name: s.storeName, image: s.storeLogoURL }));
+                        if (rows.length === 0)
+                            return null;
+                        const hrefFor = (slug) => entry.type === "categories"
+                            ? String(ROUTES.PUBLIC.CATEGORY_DETAIL(slug))
+                            : entry.type === "brands"
+                                ? String(ROUTES.PUBLIC.BRAND_DETAIL(slug))
+                                : String(ROUTES.PUBLIC.STORE_DETAIL(slug));
+                        return (_jsxs(Stack, { gap: "sm", children: [_jsx(Text, { size: "sm", weight: "semibold", color: "muted", children: entryLabel(entry) }), _jsx(Grid, { cols: "categoryCards", gap: "md", children: rows.map((row) => (_jsx(Link, { href: hrefFor(row.slug), className: "group rounded-xl border border-[var(--appkit-color-border)] transition-all hover:border-primary-300 hover:shadow-sm dark:hover:border-primary-600", children: _jsxs(Stack, { align: "center", gap: "xs", padding: "sm", children: [_jsx(Div, { className: "h-16 w-16", rounded: "lg", overflow: "hidden", children: _jsx(MediaImage, { src: row.image, alt: row.name, size: "thumbnail" }) }), _jsx(Text, { size: "xs", weight: "medium", className: "line-clamp-2", children: row.name })] }) }, row.slug))) })] }, `${entry.type}-${idx}`));
+                    }), unwiredEntries.length > 0 && (_jsx(Stack, { align: "start", gap: "sm", className: "border-dashed text-left", border: "strong", paddingY: "y-3xl", paddingX: "x-lg", rounded: "2xl", children: _jsxs(Text, { size: "sm", color: "muted", children: [unwiredEntries.map(entryLabel).join(", "), " \u2014 up to ", maxItems, " ", "items, ", itemsPerRow, " per row when wired \u2014 data wiring lands with the bundle/raffle work."] }) })), cta ? (_jsxs(Link, { href: cta.href, className: "text-[length:var(--appkit-text-sm)] font-medium text-primary hover:underline", children: [cta.label, " \u2192"] })) : null] }) }) }));
 }

package/dist/features/homepage/components/HowItWorksSection.d.ts

@@ -1,12 +1,23 @@
 import React from "react";
+import type { IconKey } from "../../../ui";
+/**
+ * Promoted to a registered `SectionType` ("how-it-works") 2026-10-19 — see
+ * `HowItWorksSectionConfig` in `schemas/firestore.ts`, which this prop shape
+ * mirrors exactly (Firestore config must be JSON-serialisable; a function
+ * value cannot round-trip through a document write).
+ *
+ * `renderIcon?: (props) => ReactNode` was the blocker: a function prop has no
+ * representation in a Firestore document. Replaced with `iconKey?: IconKey`,
+ * rendered through the shared `<Icon>` registry primitive (Root Cause #80) —
+ * the same indirection `TrustBadge.iconKey` already uses for this exact
+ * problem. `accentFrom` is dropped: declared on the old type, never read
+ * anywhere in this component.
+ */
 export interface HowItWorksStep {
     number: number;
     title: string;
     desc: string;
-    renderIcon?: (props: {
-        className?: string;
-    }) => React.ReactNode;
-    accentFrom?: string;
+    iconKey?: IconKey;
     iconColor?: string;
     iconBg?: string;
     badgeBg?: string;
@@ -16,8 +27,14 @@ export interface HowItWorksSectionProps {
     subtitle?: string;
     pillLabel?: string;
     ctaLabel?: string;
-    onCtaClick?: () => void;
+    /**
+     * A link, not a handler — `onCtaClick?: () => void` could not survive a
+     * Firestore round-trip either. Renders as an `<Anchor>`, matching how every
+     * other promoted section's CTA resolves (`EventRafflesSectionConfig`'s
+     * `cta`, `FeaturedBundlesSectionConfig`'s `viewMoreLabel` pattern, etc.).
+     */
+    ctaLink?: string;
     steps: HowItWorksStep[];
     className?: string;
 }
-export declare function HowItWorksSection({ title, subtitle, pillLabel, ctaLabel, onCtaClick, steps, className, }: HowItWorksSectionProps): React.JSX.Element;
+export declare function HowItWorksSection({ title, subtitle, pillLabel, ctaLabel, ctaLink, steps, className, }: HowItWorksSectionProps): React.JSX.Element;

package/dist/features/homepage/components/HowItWorksSection.js

@@ -2,7 +2,7 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useEffect, useRef, useState } from "react";
 import { THEMED_TEXT_PRIMARY, THEMED_TEXT_SECONDARY } from "../../../_internal/shared/styles/themed.js";
-import { Button, Div, Grid, Heading, Row, Section, Span, Text } from "../../../ui/index.js";
+import { Anchor, Button, Div, Grid, Heading, Icon, Row, Section, Span, Text } from "../../../ui/index.js";
 // --- Constants ---------------------------------------------------------------
 const CLS_VISIBLE = "opacity-100 translate-y-0";
 const STEP_DELAYS = ["delay-0", "delay-150", "delay-300", "delay-[450ms]"];
@@ -16,10 +16,10 @@ function StepCard({ step, visible, delayClass, }) {
             "transition-all duration-300",
             delayClass,
             visible ? CLS_VISIBLE : "opacity-0 translate-y-8",
-        ].join(" "), "data-section": "howitworkssection-div-340", children: [_jsx(Span, { gradient: "brand", size: "7xl", family: "display", className: "absolute top-4 right-5 opacity-10 select-none pointer-events-none leading-none", "aria-hidden": "true", children: step.number }), _jsx(Row, { textWeight: "bold", textSize: "sm", className: `relative z-10 w-10 h-10 ${badgeBg} text-white mb-5`, align: "center", justify: "center", rounded: "full", shadow: "md", children: step.number }), step.renderIcon && (_jsx(Row, { className: `relative z-10 w-14 h-14 ${iconBg} mb-4 border border-white/80 dark:border-[var(--appkit-color-border)]`, align: "center", justify: "center", rounded: "2xl", children: _jsx(Span, { className: `${iconColor}`, "aria-hidden": "true", children: step.renderIcon({ className: "w-6 h-6" }) }) })), _jsx(Heading, { level: 3, className: `relative z-10 ${THEMED_TEXT_PRIMARY} mb-2`, size: "base", weight: "semibold", children: step.title }), _jsx(Text, { className: `relative z-10 ${THEMED_TEXT_SECONDARY} leading-relaxed`, size: "sm", children: step.desc })] }));
+        ].join(" "), "data-section": "howitworkssection-div-340", children: [_jsx(Span, { gradient: "brand", size: "7xl", family: "display", className: "absolute top-4 right-5 opacity-10 select-none pointer-events-none leading-none", "aria-hidden": "true", children: step.number }), _jsx(Row, { textWeight: "bold", textSize: "sm", className: `relative z-10 w-10 h-10 ${badgeBg} text-white mb-5`, align: "center", justify: "center", rounded: "full", shadow: "md", children: step.number }), step.iconKey && (_jsx(Row, { className: `relative z-10 w-14 h-14 ${iconBg} mb-4 border border-white/80 dark:border-[var(--appkit-color-border)]`, align: "center", justify: "center", rounded: "2xl", children: _jsx(Span, { className: `${iconColor}`, "aria-hidden": "true", children: _jsx(Icon, { name: step.iconKey, size: "lg" }) }) })), _jsx(Heading, { level: 3, className: `relative z-10 ${THEMED_TEXT_PRIMARY} mb-2`, size: "base", weight: "semibold", children: step.title }), _jsx(Text, { className: `relative z-10 ${THEMED_TEXT_SECONDARY} leading-relaxed`, size: "sm", children: step.desc })] }));
 }
 // --- Section -----------------------------------------------------------------
-export function HowItWorksSection({ title, subtitle, pillLabel, ctaLabel, onCtaClick, steps, className = "", }) {
+export function HowItWorksSection({ title, subtitle, pillLabel, ctaLabel, ctaLink, steps, className = "", }) {
     const themed = { textPrimary: THEMED_TEXT_PRIMARY, textSecondary: THEMED_TEXT_SECONDARY };
     const sectionRef = useRef(null);
     const [visible, setVisible] = useState(false);
@@ -36,5 +36,5 @@ export function HowItWorksSection({ title, subtitle, pillLabel, ctaLabel, onCtaC
         observer.observe(el);
         return () => observer.disconnect();
     }, []);
-    return (_jsx(Section, { ref: sectionRef, className: `${className}`, surface: "muted", padding: "xl", children: _jsxs(Div, { className: "max-w-6xl mx-auto", children: [_jsxs(Div, { className: `text-left mb-12 transition-all duration-700 ${visible ? CLS_VISIBLE : "opacity-0 translate-y-4"}`, children: [pillLabel && (_jsx(Div, { layout: "inline-flex", gap: "2", align: "center", textWeight: "medium", textSize: "xs", className: /* audit-variant-ok: colour+alpha border (primary-500/30); the `border` variant takes a token name, not an rgba step */ "mb-4 border border-primary-500/30 bg-primary-500/10 py-[0.375rem] tracking-[0.2em] uppercase text-primary-700 dark:text-primary-400 backdrop-blur-sm", padding: "x-md", rounded: "full", children: pillLabel })), _jsx(Heading, { level: 2, className: `${themed.textPrimary} mb-3`, size: "3xl", mdSize: "4xl", weight: "bold", children: title }), subtitle && (_jsx(Text, { className: `${themed.textSecondary} max-w-xl`, size: "base", children: subtitle }))] }), _jsx(Grid, { gap: "lg", className: "grid-cols-1 md:grid-cols-3 xl:grid-cols-3 2xl:grid-cols-3 mb-10", children: steps.map((step, i) => (_jsx(StepCard, { step: step, visible: visible, delayClass: STEP_DELAYS[Math.min(i, STEP_DELAYS.length - 1)] }, step.number))) }), ctaLabel && onCtaClick && (_jsx(Div, { className: `text-left transition-all duration-700 delay-500 ${visible ? CLS_VISIBLE : "opacity-0 translate-y-4"}`, children: _jsx(Button, { variant: "primary", size: "lg", onClick: onCtaClick, children: ctaLabel }) }))] }) }));
+    return (_jsx(Section, { ref: sectionRef, className: `${className}`, surface: "muted", padding: "xl", children: _jsxs(Div, { className: "max-w-6xl mx-auto", children: [_jsxs(Div, { className: `text-left mb-12 transition-all duration-700 ${visible ? CLS_VISIBLE : "opacity-0 translate-y-4"}`, children: [pillLabel && (_jsx(Div, { layout: "inline-flex", gap: "2", align: "center", textWeight: "medium", textSize: "xs", className: /* audit-variant-ok: colour+alpha border (primary-500/30); the `border` variant takes a token name, not an rgba step */ "mb-4 border border-primary-500/30 bg-primary-500/10 py-[0.375rem] tracking-[0.2em] uppercase text-primary-700 dark:text-primary-400 backdrop-blur-sm", padding: "x-md", rounded: "full", children: pillLabel })), _jsx(Heading, { level: 2, className: `${themed.textPrimary} mb-3`, size: "3xl", mdSize: "4xl", weight: "bold", children: title }), subtitle && (_jsx(Text, { className: `${themed.textSecondary} max-w-xl`, size: "base", children: subtitle }))] }), _jsx(Grid, { gap: "lg", className: "grid-cols-1 md:grid-cols-3 xl:grid-cols-3 2xl:grid-cols-3 mb-10", children: steps.map((step, i) => (_jsx(StepCard, { step: step, visible: visible, delayClass: STEP_DELAYS[Math.min(i, STEP_DELAYS.length - 1)] }, step.number))) }), ctaLabel && ctaLink && (_jsx(Div, { className: `text-left transition-all duration-700 delay-500 ${visible ? CLS_VISIBLE : "opacity-0 translate-y-4"}`, children: _jsx(Button, { variant: "primary", size: "lg", asChild: true, children: _jsx(Anchor, { href: ctaLink, tone: "none", children: ctaLabel }) }) }))] }) }));
 }

package/dist/features/homepage/components/PromoGrid.d.ts

@@ -1,6 +1,35 @@
-import type { PromoBanner } from "../types";
+/** Hard cap — this layout only has slots for 4 (one hero tile + three). */
+export declare const PROMO_GRID_MAX_BANNERS: 4;
+/**
+ * Promoted to a registered `SectionType` ("promo-grid") 2026-10-19 — see
+ * `PromoGridSectionConfig` in `schemas/firestore.ts`.
+ *
+ * Two fixes made in the same pass:
+ * 1. `resolveMediaUrl(banner.image)!` was a non-null assertion on a function
+ *    that genuinely returns `undefined` for an empty slug — an admin saving a
+ *    banner with no image picked would crash `next/image`. The image slot now
+ *    simply renders nothing: the `<Link>` already carries its own dark
+ *    background and the gradient + caption paint on top regardless, so a
+ *    placeholder tile would have been a second element doing what the card
+ *    behind it already does.
+ * 2. `--dark-section-alt` / `--dark-section-card` / `--color-red` /
+ *    `--font-bangers` were undefined anywhere in the codebase — this
+ *    component would have rendered on a transparent background with no
+ *    borders. The section now uses the `media-dark` SURFACE TOKEN (the real
+ *    theme-invariant dark preset), plus `text-error` / `family="display"`.
+ *    It is dark in every theme by design — see `PromoGridSectionConfig`'s
+ *    docstring for why no admin background field was added (Root Cause #67).
+ */
+export interface PromoBannerConfig {
+    id: string;
+    title: string;
+    ctaLabel: string;
+    ctaUrl: string;
+    /** A media slug (`/media/<id>`), not a raw URL — resolved via `resolveMediaUrl`. */
+    image: string;
+}
 export interface PromoGridProps {
-    banners: PromoBanner[];
+    banners: PromoBannerConfig[];
     /** Eyebrow label above the section heading. Default: "LIMITED TIME". */
     eyebrow?: string;
     /** Section heading. Default: "HOT DEALS & PROMOS". */

package/dist/features/homepage/components/PromoGrid.js

@@ -6,10 +6,19 @@ import { resolveMediaUrl } from "../../../utils/media-url.js";
 const __P = {
     p4: "p-[var(--appkit-space-4)]",
 };
+/** Hard cap — this layout only has slots for 4 (one hero tile + three). */
+export const PROMO_GRID_MAX_BANNERS = 4;
 export function PromoGrid({ banners, eyebrow = "LIMITED TIME", heading = "HOT DEALS & PROMOS", }) {
     if (banners.length === 0)
         return null;
-    return (_jsx(Section, { paddingY: "y-4xl", className: "bg-[var(--dark-section-alt)] [border-top:1px_solid_rgba(255,255,255,0.06)] [border-bottom:1px_solid_rgba(255,255,255,0.06)]", children: _jsxs(Div, { className: "mx-auto max-w-7xl", padding: "x-md", children: [_jsx(Row, { wrap: true, align: "end", justify: "between", gap: "sm", className: "mb-7 gap-y-2", children: _jsxs(Div, { children: [_jsx(Text, { className: "mb-1 font-black uppercase tracking-widest text-[var(--color-red)] tracking-[0.18em]", size: "xs", children: eyebrow }), _jsx(Heading, { level: 2, className: "[font-family:var(--font-bangers,Bangers,cursive)] text-[clamp(1.6rem,4vw,2.4rem)] tracking-[0.08em] text-white leading-none", children: heading })] }) }), _jsx(Div, { layout: "grid", gap: "3", className: "grid-cols-1 sm:grid-cols-2 lg:grid-cols-3", children: banners.slice(0, 4).map((banner, i) => (_jsxs(Link, { href: banner.ctaUrl, className: `group relative block overflow-hidden bg-[var(--dark-section-card)] ${i === 0 ? "sm:row-span-2 min-h-[clamp(220px,32vh,480px)]" : "min-h-[clamp(130px,16vh,240px)]"}`, children: [_jsx(Image, { src: resolveMediaUrl(banner.image), alt: banner.title, fill: true, className: "object-cover transition-transform duration-500 group-hover:scale-105", sizes: i === 0
-                                    ? "(max-width: 640px) 100vw, 40vw"
-                                    : "(max-width: 640px) 50vw, 30vw" }), _jsx(Div, { className: `absolute inset-0 ${i === 0 ? "[background:linear-gradient(to_top,rgba(0,0,0,0.9)_0%,rgba(0,0,0,0.3)_50%,transparent_100%)]" : "[background:linear-gradient(to_top,rgba(0,0,0,0.85)_0%,rgba(0,0,0,0.15)_100%)]"}` }), _jsx(Div, { className: "absolute inset-0 pointer-events-none opacity-0 transition-opacity duration-300 group-hover:opacity-100 ring-2 ring-[var(--color-yellow)] ring-inset" }), _jsxs(Div, { className: `absolute bottom-0 left-0 right-0 ${__P.p4}`, children: [_jsx(Text, { className: `leading-tight [font-family:var(--font-bangers,Bangers,cursive)] tracking-[0.06em] text-white ${i === 0 ? "text-[1.35rem]" : "text-[1rem]"}`, children: banner.title }), _jsxs(Span, { layout: "inline-flex", gap: "xs", className: "mt-1 font-black uppercase text-[var(--color-yellow)]", size: "xs", children: [banner.ctaLabel, " \u2192"] })] })] }, banner.id))) })] }) }));
+    return (_jsx(Section, { paddingY: "y-4xl", 
+        // `media-dark` IS the theme-invariant dark surface token (bg-zinc-900)
+        // — exactly what this always-dark section needs, so no raw className
+        // colour and no suppression marker.
+        surface: "media-dark", className: "border-t border-b border-white/[0.06]", children: _jsxs(Div, { className: "mx-auto max-w-7xl", padding: "x-md", children: [_jsx(Row, { wrap: true, align: "end", justify: "between", gap: "sm", className: "mb-7 gap-y-2", children: _jsxs(Div, { children: [_jsx(Text, { className: "mb-1 font-black uppercase tracking-widest text-error tracking-[0.18em]", size: "xs", children: eyebrow }), _jsx(Heading, { level: 2, family: "display", className: "tracking-[0.08em] leading-none text-white", size: "xl", mdSize: "2xl", weight: "bold", children: heading })] }) }), _jsx(Div, { layout: "grid", gap: "3", className: "grid-cols-1 sm:grid-cols-2 lg:grid-cols-3", children: banners.slice(0, PROMO_GRID_MAX_BANNERS).map((banner, i) => {
+                        const resolvedSrc = resolveMediaUrl(banner.image);
+                        return (_jsxs(Link, { href: banner.ctaUrl, className: `group relative block overflow-hidden bg-zinc-900 ${i === 0 ? "sm:row-span-2 min-h-[clamp(220px,32vh,480px)]" : "min-h-[clamp(130px,16vh,240px)]"}`, children: [resolvedSrc ? (_jsx(Image, { src: resolvedSrc, alt: banner.title, fill: true, className: "object-cover transition-transform duration-500 group-hover:scale-105", sizes: i === 0
+                                        ? "(max-width: 640px) 100vw, 40vw"
+                                        : "(max-width: 640px) 50vw, 30vw" })) : null, _jsx(Div, { className: `absolute inset-0 ${i === 0 ? "[background:linear-gradient(to_top,rgba(0,0,0,0.9)_0%,rgba(0,0,0,0.3)_50%,transparent_100%)]" : "[background:linear-gradient(to_top,rgba(0,0,0,0.85)_0%,rgba(0,0,0,0.15)_100%)]"}` }), _jsx(Div, { className: "absolute inset-0 pointer-events-none opacity-0 transition-opacity duration-300 group-hover:opacity-100 ring-2 ring-[var(--color-yellow)] ring-inset" }), _jsxs(Div, { className: `absolute bottom-0 left-0 right-0 ${__P.p4}`, children: [_jsx(Text, { family: "display", className: `leading-tight tracking-[0.06em] text-white ${i === 0 ? "text-[1.35rem]" : "text-[1rem]"}`, children: banner.title }), _jsxs(Span, { layout: "inline-flex", gap: "xs", className: "mt-1 font-black uppercase text-[var(--color-yellow)]", size: "xs", children: [banner.ctaLabel, " \u2192"] })] })] }, banner.id));
+                    }) })] }) }));
 }