@mohasinac/appkit 4.53.2 → 4.54.1

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

@@ -11,4 +11,32 @@ export interface WhatsAppCommunitySectionProps {
     isLoading?: boolean;
     className?: string;
 }
+/**
+ * The community invite.
+ *
+ * ## 🛑 It looks like a chat because it IS a chat invite
+ *
+ * This was a single flat card: icon row → heading → description → a 2-column
+ * grid of four identical `✓` circles → an italic blockquote → a button, all
+ * left-aligned in one top-down stack. Two of those blocks (the `✓` grid and the
+ * blockquote) spent a lot of vertical space *telling* you the group is useful.
+ * As bubbles on WhatsApp's own wallpaper they *show* it, in less room.
+ *
+ * Everything needed already existed and had no consumer: `Card`'s
+ * `chat-bubble-mine` / `chat-bubble-theirs` variants (with the correct corner
+ * notches and an auto-margin for right alignment) and the
+ * `--appkit-color-whatsapp-bg` beige token.
+ *
+ * ## 🛑 Three things that are deliberate
+ *
+ * 1. **No fabricated timestamps and no `✓✓` read receipts.** Tempting, and the
+ *    same category of claim as a made-up member count — which this feature
+ *    already refuses to invent. The bubble shape carries the motif on its own.
+ * 2. **`align="start"` on the thread is load-bearing.** `chat-bubble-*` is
+ *    `display:inline-block; max-width:80%`, and a stretched flex item defeats
+ *    both, so the bubbles would become full-width boxes.
+ * 3. **`tone="whatsapp"`, not `tone="accent-banner"`.** The old tone is brand
+ *    primary→secondary — the SAME gradient as `CTABannerSection` a couple of
+ *    sections below, which is a real part of why the page read monotonous.
+ */
 export declare function WhatsAppCommunitySection({ title, descriptionHtml, memberCount, memberCountLabel, testimonial, benefits, buttonText, groupLink, isLoading, className, }: WhatsAppCommunitySectionProps): React.JSX.Element | null;

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

@@ -1,12 +1,38 @@
 "use client";
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { Blockquote, Button, Div, Heading, RichText, Row, Section, Span, Text } from "../../../ui/index.js";
-import { Users } from "lucide-react";
+import { Button, Card, Div, Grid, Heading, Icon, RichText, Row, Section, Span, Stack, Text } from "../../../ui/index.js";
 import { getDefaultLocale } from "../../../core/baseline-resolver.js";
-import { useHandMode } from "../../../_internal/client/hand-mode/index.js";
+import { WhatsAppGlyph } from "./WhatsAppGlyph.js";
 // --- Section -----------------------------------------------------------------
+/**
+ * The community invite.
+ *
+ * ## 🛑 It looks like a chat because it IS a chat invite
+ *
+ * This was a single flat card: icon row → heading → description → a 2-column
+ * grid of four identical `✓` circles → an italic blockquote → a button, all
+ * left-aligned in one top-down stack. Two of those blocks (the `✓` grid and the
+ * blockquote) spent a lot of vertical space *telling* you the group is useful.
+ * As bubbles on WhatsApp's own wallpaper they *show* it, in less room.
+ *
+ * Everything needed already existed and had no consumer: `Card`'s
+ * `chat-bubble-mine` / `chat-bubble-theirs` variants (with the correct corner
+ * notches and an auto-margin for right alignment) and the
+ * `--appkit-color-whatsapp-bg` beige token.
+ *
+ * ## 🛑 Three things that are deliberate
+ *
+ * 1. **No fabricated timestamps and no `✓✓` read receipts.** Tempting, and the
+ *    same category of claim as a made-up member count — which this feature
+ *    already refuses to invent. The bubble shape carries the motif on its own.
+ * 2. **`align="start"` on the thread is load-bearing.** `chat-bubble-*` is
+ *    `display:inline-block; max-width:80%`, and a stretched flex item defeats
+ *    both, so the bubbles would become full-width boxes.
+ * 3. **`tone="whatsapp"`, not `tone="accent-banner"`.** The old tone is brand
+ *    primary→secondary — the SAME gradient as `CTABannerSection` a couple of
+ *    sections below, which is a real part of why the page read monotonous.
+ */
 export function WhatsAppCommunitySection({ title, descriptionHtml, memberCount, memberCountLabel = "members", testimonial, benefits = [], buttonText = "Join our WhatsApp community", groupLink, isLoading = false, className = "", }) {
-    const { hand } = useHandMode();
     if (isLoading) {
         return (_jsx(Section, { paddingX: "x-md-2xl", className: className, surface: "subtle", paddingY: "y-4xl", children: _jsx(Div, { className: "w-full max-w-7xl mx-auto", children: _jsx(Div, { className: "h-72 animate-pulse", surface: "subtle", rounded: "2xl" }) }) }));
     }
@@ -14,7 +40,17 @@ export function WhatsAppCommunitySection({ title, descriptionHtml, memberCount,
         return null;
     const handleJoin = () => {
         if (groupLink)
-            window.open(groupLink, "_blank");
+            window.open(groupLink, "_blank", "noopener,noreferrer");
     };
-    return (_jsx(Section, { paddingX: "x-md-2xl", className: className, surface: "subtle", paddingY: "y-4xl", children: _jsx(Div, { className: "w-full max-w-7xl mx-auto", children: _jsxs(Section, { color: "inverse", tone: "accent-banner", rounded: "2xl", shadow: "lg", className: "relative overflow-hidden", children: [_jsx(Div, { className: "absolute inset-0 opacity-[0.06] pointer-events-none bg-[repeating-linear-gradient(45deg,white_0,white_1px,transparent_0,transparent_50%)] bg-[size:10px_10px]", "aria-hidden": true }), _jsxs(Div, { className: "relative z-10 px-[1.5rem] sm:px-[2.5rem] sm:py-[3rem]", padding: "y-2xl", children: [_jsxs(Row, { align: "center", justify: "between", gap: "md", wrap: true, className: "mb-8", reverse: hand === "left", children: [_jsxs(Row, { align: "center", gap: "3", children: [_jsx(Row, { className: "w-12 h-12 bg-[var(--appkit-color-whatsapp)] flex-shrink-0", align: "center", justify: "center", rounded: "xl", shadow: "lg", children: _jsx("svg", { className: "w-7 h-7 text-white", fill: "currentColor", viewBox: "0 0 24 24", "aria-hidden": "true", children: _jsx("path", { d: "M17.472 14.382c-.297-.149-1.758-.867-2.03-.967-.273-.099-.471-.148-.67.15-.197.297-.767.966-.94 1.164-.173.199-.347.223-.644.075-.297-.15-1.255-.463-2.39-1.475-.883-.788-1.48-1.761-1.653-2.059-.173-.297-.018-.458.13-.606.134-.133.298-.347.446-.52.149-.174.198-.298.298-.497.099-.198.05-.371-.025-.52-.075-.149-.669-1.612-.916-2.207-.242-.579-.487-.5-.669-.51-.173-.008-.371-.01-.57-.01-.198 0-.52.074-.792.372-.272.297-1.04 1.016-1.04 2.479 0 1.462 1.065 2.875 1.213 3.074.149.198 2.096 3.2 5.077 4.487.709.306 1.262.489 1.694.625.712.227 1.36.195 1.871.118.571-.085 1.758-.719 2.006-1.413.248-.694.248-1.289.173-1.413-.074-.124-.272-.198-.57-.347m-5.421 7.403h-.004a9.87 9.87 0 01-5.031-1.378l-.361-.214-3.741.982.998-3.648-.235-.374a9.86 9.86 0 01-1.51-5.26c.001-5.45 4.436-9.884 9.888-9.884 2.64 0 5.122 1.03 6.988 2.898a9.825 9.825 0 012.893 6.994c-.003 5.45-4.437 9.884-9.885 9.884m8.413-18.297A11.815 11.815 0 0012.05 0C5.495 0 .16 5.335.157 11.892c0 2.096.547 4.142 1.588 5.945L.057 24l6.305-1.654a11.882 11.882 0 005.683 1.448h.005c6.554 0 11.89-5.335 11.893-11.893a11.821 11.821 0 00-3.48-8.413z" }) }) }), _jsx(Span, { color: "inverse", size: "sm", weight: "medium", className: "/80 tracking-wide", transform: "uppercase", children: "WhatsApp Community" })] }), memberCount && (_jsxs(Row, { paddingY: "y-2xs-tall", className: "backdrop-blur-sm", surface: "frost", padding: "x-md", align: "center", gap: "sm", rounded: "full", children: [_jsx(Users, { className: "w-4 h-4 text-white/80" }), _jsxs(Span, { color: "inverse", size: "sm", weight: "semibold", children: [memberCount.toLocaleString(getDefaultLocale()), "+ ", memberCountLabel] })] }))] }), _jsx(Heading, { color: "inverse", level: 2, className: "mb-3 leading-tight", smSize: "3xl", size: "2xl", weight: "bold", children: title }), descriptionHtml && (_jsx(RichText, { html: descriptionHtml, proseClass: "prose prose-sm max-w-none prose-invert", className: "text-white/80 text-[length:var(--appkit-text-base)] mb-6 max-w-2xl leading-relaxed" })), benefits.length > 0 && (_jsx(Div, { layout: "grid", gap: "3", className: "grid-cols-1 sm:grid-cols-2 mb-8 max-w-2xl", children: benefits.slice(0, 4).map((benefit, i) => (_jsxs(Row, { align: "start", gap: "2.5", children: [_jsx(Span, { layout: "flex-center", className: "mt-0.5 flex-shrink-0 w-5 h-5 bg-[rgba(255,255,255,0.2)]", rounded: "full", children: _jsx("svg", { className: "w-3 h-3 text-white", fill: "currentColor", viewBox: "0 0 20 20", "aria-hidden": "true", children: _jsx("path", { fillRule: "evenodd", d: "M16.707 5.293a1 1 0 010 1.414l-8 8a1 1 0 01-1.414 0l-4-4a1 1 0 011.414-1.414L8 12.586l7.293-7.293a1 1 0 011.414 0z", clipRule: "evenodd" }) }) }), _jsx(Span, { color: "inverse", size: "sm", className: "/90 leading-snug", children: benefit })] }, i))) })), testimonial && (_jsx(Blockquote, { paddingX: "x-md", className: "border-l-2 border-white/30 mb-8 max-w-xl", children: _jsxs(Text, { color: "inverse", variant: "none", className: "/75 italic leading-relaxed", size: "sm", children: ["\u201C", testimonial, "\u201D"] }) })), groupLink && (_jsxs(Button, { gap: "md", variant: "primary", size: "lg", onClick: handleJoin, "aria-label": buttonText, className: "!bg-[var(--appkit-color-whatsapp)] hover:!bg-[var(--appkit-color-whatsapp-light)] !text-white !border-0 font-[600]", shadow: "lg", children: [_jsx("svg", { className: "w-5 h-5 shrink-0", fill: "currentColor", viewBox: "0 0 24 24", "aria-hidden": "true", children: _jsx("path", { d: "M17.472 14.382c-.297-.149-1.758-.867-2.03-.967-.273-.099-.471-.148-.67.15-.197.297-.767.966-.94 1.164-.173.199-.347.223-.644.075-.297-.15-1.255-.463-2.39-1.475-.883-.788-1.48-1.761-1.653-2.059-.173-.297-.018-.458.13-.606.134-.133.298-.347.446-.52.149-.174.198-.298.298-.497.099-.198.05-.371-.025-.52-.075-.149-.669-1.612-.916-2.207-.242-.579-.487-.5-.669-.51-.173-.008-.371-.01-.57-.01-.198 0-.52.074-.792.372-.272.297-1.04 1.016-1.04 2.479 0 1.462 1.065 2.875 1.213 3.074.149.198 2.096 3.2 5.077 4.487.709.306 1.262.489 1.694.625.712.227 1.36.195 1.871.118.571-.085 1.758-.719 2.006-1.413.248-.694.248-1.289.173-1.413-.074-.124-.272-.198-.57-.347m-5.421 7.403h-.004a9.87 9.87 0 01-5.031-1.378l-.361-.214-3.741.982.998-3.648-.235-.374a9.86 9.86 0 01-1.51-5.26c.001-5.45 4.436-9.884 9.888-9.884 2.64 0 5.122 1.03 6.988 2.898a9.825 9.825 0 012.893 6.994c-.003 5.45-4.437 9.884-9.885 9.884m8.413-18.297A11.815 11.815 0 0012.05 0C5.495 0 .16 5.335.157 11.892c0 2.096.547 4.142 1.588 5.945L.057 24l6.305-1.654a11.882 11.882 0 005.683 1.448h.005c6.554 0 11.89-5.335 11.893-11.893a11.821 11.821 0 00-3.48-8.413z" }) }), buttonText] }))] })] }) }) }));
+    /* The thread. Benefits read as incoming messages; the testimonial closes it.
+       Below two there is no conversation to show, so the panel stands down and
+       the pitch column takes the full width rather than sitting beside an
+       almost-empty box. */
+    const thread = [...benefits.slice(0, 4), ...(testimonial ? [`“${testimonial}”`] : [])];
+    const showThread = thread.length >= 2;
+    return (_jsx(Section, { paddingX: "x-md-2xl", className: className, surface: "subtle", paddingY: "y-4xl", children: _jsx(Div, { className: "w-full max-w-7xl mx-auto", children: _jsxs(Section, { color: "inverse", tone: "whatsapp", rounded: "3xl", shadow: "xl", className: "relative overflow-hidden", children: [_jsx(Div, { className: "absolute inset-0 opacity-[0.10] pointer-events-none bg-[radial-gradient(circle_at_1px_1px,white_1px,transparent_0)] bg-[size:18px_18px]", "aria-hidden": true }), _jsxs(Grid, { cols: showThread ? "halves" : "autoLg", gap: "hero", align: "center", className: "relative z-10 px-[1.5rem] py-[2.5rem] sm:px-[2.5rem] sm:py-[3rem]", children: [_jsxs(Stack, { gap: "lg", children: [_jsxs(Row, { align: "center", gap: "md", wrap: true, children: [_jsxs(Row, { surface: "frost", rounded: "full", padding: "x-sm", paddingY: "y-2xs-tall", align: "center", gap: "xs", className: "backdrop-blur-sm", children: [_jsx(WhatsAppGlyph, { className: "h-4 w-4" }), _jsx(Span, { color: "inverse", size: "xs", weight: "semibold", transform: "uppercase", className: "tracking-[0.18em]", children: "WhatsApp Community" })] }), memberCount && (_jsxs(Row, { align: "center", gap: "xs", children: [_jsxs(Span, { layout: "flex", className: "relative h-2 w-2", "aria-hidden": true, children: [_jsx(Span, { rounded: "full", className: "absolute inline-flex h-full w-full animate-ping bg-[var(--appkit-color-surface)] opacity-75" }), _jsx(Span, { rounded: "full", className: "relative inline-flex h-2 w-2 bg-[var(--appkit-color-surface)]" })] }), _jsxs(Span, { color: "inverse-muted", size: "xs", weight: "medium", numeric: true, children: [memberCount.toLocaleString(getDefaultLocale()), "+ ", memberCountLabel] })] }))] }), _jsx(Heading, { color: "inverse", level: 2, size: "3xl", mdSize: "4xl", weight: "bold", className: "leading-[1.1] tracking-tight", children: title }), descriptionHtml && (
+                                    /* No colour class here. `prose-invert` sets `--tw-prose-body`
+                                       itself, so ANY wrapper colour loses to it — the previous
+                                       `text-white/80` on this element did nothing. */
+                                    _jsx(RichText, { html: descriptionHtml, proseClass: "prose prose-sm prose-invert max-w-none", className: "max-w-md text-[length:var(--appkit-text-base)] leading-relaxed" })), groupLink && (_jsx(Row, { children: _jsxs(Button, { variant: "inverse", size: "lg", shadow: "lg", gap: "md", onClick: handleJoin, "aria-label": buttonText, children: [_jsx(WhatsAppGlyph, { className: "h-5 w-5" }), buttonText] }) }))] }), showThread && (_jsxs(Stack, { gap: "sm", align: "start", rounded: "2xl", padding: "md", shadow: "2xl", className: "bg-[var(--appkit-color-whatsapp-bg)]", role: "img", "aria-label": "Example messages from the community group", children: [thread.map((line, i) => (_jsx(Card, { padding: "none", variant: i % 2 === 1 ? "chat-bubble-mine" : "chat-bubble-theirs", children: _jsx(Text, { size: "sm", className: "leading-snug", children: line }) }, i))), _jsxs(Row, { align: "center", gap: "xs", className: "self-end pt-[var(--appkit-space-1)]", children: [_jsx(Icon, { name: "lock", size: "xs", tone: "muted" }), _jsx(Span, { size: "xs", color: "muted", children: "End-to-end encrypted by WhatsApp" })] })] }))] })] }) }) }));
 }

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

@@ -0,0 +1,20 @@
+import React from "react";
+/**
+ * The WhatsApp brand mark.
+ *
+ * ## 🛑 Why this is NOT in `icon-registry.ts`
+ *
+ * That registry's keys are INTENT names (`verify`, `restore`, `ship`) resolving
+ * to lucide glyphs, and its header is explicit that it is deliberately small
+ * and not a re-export of an icon set. A third-party brand mark is neither an
+ * intent nor a lucide glyph — registering it would make "which icon set is this
+ * key from?" a question with two answers.
+ *
+ * It lives here because it was inlined TWICE in `WhatsAppCommunitySection`
+ * (~1.2KB of identical path data in one file), and the second copy had no
+ * `shrink-0`, so inside a padded flex control it could shrink below its stated
+ * size — Root Cause #80's `UNSHRINKABLE_GLYPH`.
+ */
+export declare function WhatsAppGlyph({ className }: {
+    className?: string;
+}): React.JSX.Element;

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

@@ -0,0 +1,20 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+/**
+ * The WhatsApp brand mark.
+ *
+ * ## 🛑 Why this is NOT in `icon-registry.ts`
+ *
+ * That registry's keys are INTENT names (`verify`, `restore`, `ship`) resolving
+ * to lucide glyphs, and its header is explicit that it is deliberately small
+ * and not a re-export of an icon set. A third-party brand mark is neither an
+ * intent nor a lucide glyph — registering it would make "which icon set is this
+ * key from?" a question with two answers.
+ *
+ * It lives here because it was inlined TWICE in `WhatsAppCommunitySection`
+ * (~1.2KB of identical path data in one file), and the second copy had no
+ * `shrink-0`, so inside a padded flex control it could shrink below its stated
+ * size — Root Cause #80's `UNSHRINKABLE_GLYPH`.
+ */
+export function WhatsAppGlyph({ className = "" }) {
+    return (_jsx("svg", { className: `shrink-0 ${className}`, fill: "currentColor", viewBox: "0 0 24 24", "aria-hidden": "true", children: _jsx("path", { d: "M17.472 14.382c-.297-.149-1.758-.867-2.03-.967-.273-.099-.471-.148-.67.15-.197.297-.767.966-.94 1.164-.173.199-.347.223-.644.075-.297-.15-1.255-.463-2.39-1.475-.883-.788-1.48-1.761-1.653-2.059-.173-.297-.018-.458.13-.606.134-.133.298-.347.446-.52.149-.174.198-.298.298-.497.099-.198.05-.371-.025-.52-.075-.149-.669-1.612-.916-2.207-.242-.579-.487-.5-.669-.51-.173-.008-.371-.01-.57-.01-.198 0-.52.074-.792.372-.272.297-1.04 1.016-1.04 2.479 0 1.462 1.065 2.875 1.213 3.074.149.198 2.096 3.2 5.077 4.487.709.306 1.262.489 1.694.625.712.227 1.36.195 1.871.118.571-.085 1.758-.719 2.006-1.413.248-.694.248-1.289.173-1.413-.074-.124-.272-.198-.57-.347m-5.421 7.403h-.004a9.87 9.87 0 01-5.031-1.378l-.361-.214-3.741.982.998-3.648-.235-.374a9.86 9.86 0 01-1.51-5.26c.001-5.45 4.436-9.884 9.888-9.884 2.64 0 5.122 1.03 6.988 2.898a9.825 9.825 0 012.893 6.994c-.003 5.45-4.437 9.884-9.885 9.884m8.413-18.297A11.815 11.815 0 0012.05 0C5.495 0 .16 5.335.157 11.892c0 2.096.547 4.142 1.588 5.945L.057 24l6.305-1.654a11.882 11.882 0 005.683 1.448h.005c6.554 0 11.89-5.335 11.893-11.893a11.821 11.821 0 00-3.48-8.413z" }) }));
+}

package/dist/features/homepage/constants/hero-carousel-styles.d.ts

@@ -1,12 +1,14 @@
 /**
- * HeroCarousel-specific class strings (arrow + active/inactive dots).
+ * HeroCarousel-specific class strings.
  *
- * Extracted from `THEME_CONSTANTS.carousel.{arrow,dotActive,dotInactive}`
- * so the consumer sweep can drop the THEME_CONSTANTS dependency.
+ * 🛑 `HERO_CAROUSEL_ARROW`, `HERO_CAROUSEL_DOT_ACTIVE` and
+ * `HERO_CAROUSEL_DOT_INACTIVE` were DELETED 2026-10-20 along with the markup
+ * that consumed them. They were one of three unrelated carousel-indicator
+ * implementations on the homepage; all three are now
+ * `ui/components/CarouselNav`, whose docstring records what each of them got
+ * wrong. Do not reintroduce a per-surface dot or arrow style here — a second
+ * appearance is how the three diverged in the first place.
  */
-export declare const HERO_CAROUSEL_ARROW = "w-10 h-10 rounded-2xl bg-[color-mix(in_srgb,var(--appkit-color-surface)_85%,transparent)] backdrop-blur-sm shadow-lg border border-[var(--appkit-color-border)] text-[var(--appkit-color-text)] hover:-translate-y-0.5 hover:bg-[var(--appkit-color-surface)] hover:shadow-xl active:scale-95 transition-all duration-200 flex items-center justify-center";
-export declare const HERO_CAROUSEL_DOT_ACTIVE = "w-8 h-2 !min-h-0 rounded-full bg-[var(--appkit-color-surface)] shadow-sm transition-all duration-500";
-export declare const HERO_CAROUSEL_DOT_INACTIVE = "w-2 h-2 !min-h-0 rounded-full bg-white/55 shadow-sm transition-all duration-500";
 /** Absolute fill helper — `position: absolute; inset: 0`. */
 export declare const POSITION_FILL = "absolute inset-0";
 /** Flex centering helper — `flex items-center justify-center`. */

package/dist/features/homepage/constants/hero-carousel-styles.js

@@ -1,12 +1,14 @@
 /**
- * HeroCarousel-specific class strings (arrow + active/inactive dots).
+ * HeroCarousel-specific class strings.
  *
- * Extracted from `THEME_CONSTANTS.carousel.{arrow,dotActive,dotInactive}`
- * so the consumer sweep can drop the THEME_CONSTANTS dependency.
+ * 🛑 `HERO_CAROUSEL_ARROW`, `HERO_CAROUSEL_DOT_ACTIVE` and
+ * `HERO_CAROUSEL_DOT_INACTIVE` were DELETED 2026-10-20 along with the markup
+ * that consumed them. They were one of three unrelated carousel-indicator
+ * implementations on the homepage; all three are now
+ * `ui/components/CarouselNav`, whose docstring records what each of them got
+ * wrong. Do not reintroduce a per-surface dot or arrow style here — a second
+ * appearance is how the three diverged in the first place.
  */
-export const HERO_CAROUSEL_ARROW = "w-10 h-10 rounded-2xl bg-[color-mix(in_srgb,var(--appkit-color-surface)_85%,transparent)] backdrop-blur-sm shadow-lg border border-[var(--appkit-color-border)] text-[var(--appkit-color-text)] hover:-translate-y-0.5 hover:bg-[var(--appkit-color-surface)] hover:shadow-xl active:scale-95 transition-all duration-200 flex items-center justify-center";
-export const HERO_CAROUSEL_DOT_ACTIVE = "w-8 h-2 !min-h-0 rounded-full bg-[var(--appkit-color-surface)] shadow-sm transition-all duration-500";
-export const HERO_CAROUSEL_DOT_INACTIVE = "w-2 h-2 !min-h-0 rounded-full bg-white/55 shadow-sm transition-all duration-500";
 /** Absolute fill helper — `position: absolute; inset: 0`. */
 export const POSITION_FILL = "absolute inset-0";
 /** Flex centering helper — `flex items-center justify-center`. */

package/dist/features/homepage/constants/section-copy.d.ts

@@ -71,8 +71,10 @@ export declare const SECTION_COPY: {
     readonly featuresPill: "Built for trust";
     readonly featuresLearnMore: "Learn about our security →";
     readonly bannerPrimaryCta: "Shop All Products →";
-    readonly bannerSecondaryCta: "Browse Auctions →";
-    readonly whatsappDescription: "Get deal alerts, auction updates, and exclusive drops before anyone else.";
+    readonly bannerSecondaryCta: "Browse Categories →";
+    /** Eyebrow above the CTA banner headline — replaces a decorative ✨. */
+    readonly bannerEyebrow: "Start here";
+    readonly whatsappDescription: "Get deal alerts, new arrivals, and exclusive drops before anyone else.";
     /**
      * Shown only when `siteSettings.announcementBar` has no message. Was a
      * hardcoded seasonal Pokémon TCG discount, which would have gone out as
@@ -90,18 +92,18 @@ export declare const SECTION_COPY: {
  */
 export declare const WELCOME_TRUST_CHIPS: readonly [{
     readonly key: "delivery";
-    readonly emoji: "🚀";
-    readonly label: "Fast Delivery";
+    readonly iconName: "ship";
+    readonly label: "Fast delivery";
 }, {
     readonly key: "secure";
-    readonly emoji: "🔒";
-    readonly label: "Secure Payments";
+    readonly iconName: "lock";
+    readonly label: "Secure payments";
 }, {
     readonly key: "rating";
-    readonly emoji: "⭐";
-    readonly label: "Buyer Rated";
+    readonly iconName: "review";
+    readonly label: "Buyer rated";
 }, {
     readonly key: "returns";
-    readonly emoji: "↩️";
-    readonly label: "Easy Returns";
+    readonly iconName: "restore";
+    readonly label: "Easy returns";
 }];

package/dist/features/homepage/constants/section-copy.js

@@ -71,8 +71,18 @@ export const SECTION_COPY = {
     featuresPill: "Built for trust",
     featuresLearnMore: "Learn about our security →",
     bannerPrimaryCta: "Shop All Products →",
-    bannerSecondaryCta: "Browse Auctions →",
-    whatsappDescription: "Get deal alerts, auction updates, and exclusive drops before anyone else.",
+    /*
+     * 🛑 Not "Browse Auctions →". The CTA banner is NOT in
+     * `HOMEPAGE_SECTION_LISTING_TYPE`, so unlike the auctions rail it is never
+     * gated — it renders whatever this says on a site running
+     * `listings.listingTypes.auction: false`, which is a button on the homepage
+     * leading to a browse page with nothing in it. The `secondaryHref` default in
+     * CTABannerSection.tsx moved with it; they are one control in two files.
+     */
+    bannerSecondaryCta: "Browse Categories →",
+    /** Eyebrow above the CTA banner headline — replaces a decorative ✨. */
+    bannerEyebrow: "Start here",
+    whatsappDescription: "Get deal alerts, new arrivals, and exclusive drops before anyone else.",
     /**
      * Shown only when `siteSettings.announcementBar` has no message. Was a
      * hardcoded seasonal Pokémon TCG discount, which would have gone out as
@@ -89,8 +99,20 @@ export const SECTION_COPY = {
  * Revisit if a consumer needs different ones.
  */
 export const WELCOME_TRUST_CHIPS = [
-    { key: "delivery", emoji: "🚀", label: "Fast Delivery" },
-    { key: "secure", emoji: "🔒", label: "Secure Payments" },
-    { key: "rating", emoji: "⭐", label: "Buyer Rated" },
-    { key: "returns", emoji: "↩️", label: "Easy Returns" },
+    /*
+     * 🛑 Registry icon keys, not emoji.
+     *
+     * An emoji cannot be sized — no width or height utility reaches a text
+     * character, so it renders at whatever the platform font fallback is, next to
+     * a label that IS sized (Root Cause #80). It is also a different glyph on
+     * every OS, which is the opposite of a design system.
+     *
+     * `🚀` was additionally just wrong: a rocket is not delivery. `ship` is a
+     * truck. Labels are sentence case — Title Case On Four Short Chips reads
+     * dated on its own.
+     */
+    { key: "delivery", iconName: "ship", label: "Fast delivery" },
+    { key: "secure", iconName: "lock", label: "Secure payments" },
+    { key: "rating", iconName: "review", label: "Buyer rated" },
+    { key: "returns", iconName: "restore", label: "Easy returns" },
 ];

package/dist/features/homepage/constants/stat-icons.d.ts

@@ -0,0 +1,12 @@
+import type { LiveStatPreset } from "../schemas/firestore";
+import type { IconKey } from "../../../ui/icons/icon-registry";
+/**
+ * `LiveStatPreset` → the glyph that means it.
+ *
+ * A live stat therefore gets a correct icon with ZERO config: the preset is
+ * already a closed 6-member union, so the icon is derivable from what the stat
+ * measures rather than being a second thing an admin has to fill in and keep
+ * consistent. Declared `Record<LiveStatPreset, IconKey>` so a seventh preset
+ * is a compile error here rather than a silently iconless tile.
+ */
+export declare const STAT_PRESET_ICON: Record<LiveStatPreset, IconKey>;

package/dist/features/homepage/constants/stat-icons.js

@@ -0,0 +1,17 @@
+/**
+ * `LiveStatPreset` → the glyph that means it.
+ *
+ * A live stat therefore gets a correct icon with ZERO config: the preset is
+ * already a closed 6-member union, so the icon is derivable from what the stat
+ * measures rather than being a second thing an admin has to fill in and keep
+ * consistent. Declared `Record<LiveStatPreset, IconKey>` so a seventh preset
+ * is a compile error here rather than a silently iconless tile.
+ */
+export const STAT_PRESET_ICON = {
+    total_listings: "order",
+    verified_sellers: "verify",
+    total_buyers: "user",
+    platform_rating: "review",
+    total_orders: "cart",
+    total_reviews: "message",
+};

package/dist/features/homepage/constants/trust-icon-aliases.d.ts

@@ -0,0 +1,8 @@
+import { type IconKey } from "../../../ui/icons/icon-registry";
+/**
+ * Resolve a stored icon string to a registry key.
+ *
+ * Accepts an already-valid `IconKey` unchanged, so a value authored after the
+ * admin editor moved to a key picker needs no alias entry.
+ */
+export declare function resolveTrustIcon(stored: string | undefined | null): IconKey | undefined;

package/dist/features/homepage/constants/trust-icon-aliases.js

@@ -0,0 +1,75 @@
+import { isIconKey } from "../../../ui/icons/icon-registry.js";
+/**
+ * Stored icon strings → `IconKey`s, for the trust / security / stats tiles.
+ *
+ * ## 🛑 Why an alias map and not a retype
+ *
+ * `TrustIndicator.icon` is a `string` and live documents hold TWO unrelated
+ * spellings of it:
+ *
+ *   - kebab lucide names, from the seed — `"shield-check"`, `"rotate-ccw"`,
+ *     `"message-circle"`;
+ *   - intent slugs, from `section-defaults.ts` — `"secure-payments"`,
+ *     `"fast-delivery"`, `"easy-returns"`, `"support"`.
+ *
+ * Neither set is a valid `IconKey` (the registry is intent-named: `verify`,
+ * `restore`, `message`…), so retyping the field would invalidate every stored
+ * document at once. Mapping instead means existing admin-authored values keep
+ * working and the field stays editable.
+ *
+ * ## 🛑 Why the icon was invisible before this existed
+ *
+ * All three components declared `renderIcon?: (props) => ReactNode` and the
+ * section renderer never passed it — a function prop has no representation in a
+ * Firestore document, so it was unreachable by construction. The result was
+ * four trust tiles rendering the same hardcoded `✓` while four *different*
+ * promises sat beside them, and no icon at all on the stats and security
+ * tiles. The admin editor round-tripped `icon` the whole time and the component
+ * used it only as a React key. Root Cause #51.
+ *
+ * An unmapped value resolves to `undefined` and the tile renders text-only,
+ * which is strictly better than one glyph standing in for everything.
+ */
+const TRUST_ICON_ALIASES = {
+    // Lucide kebab names, as written by the seed and the admin editor.
+    "shield-check": "verify",
+    lock: "lock",
+    "rotate-ccw": "restore",
+    "message-circle": "message",
+    truck: "ship",
+    star: "review",
+    package: "order",
+    "trending-up": "analytics",
+    "help-circle": "help",
+    tag: "deals",
+    flag: "report",
+    // Intent slugs, as written by DEFAULT_TRUST_FEATURES.
+    "secure-payments": "lock",
+    "fast-delivery": "ship",
+    "easy-returns": "restore",
+    support: "help",
+    authenticity: "verify",
+    // Intent slugs, as written by the `features` seed config.
+    escrow: "lock",
+    "verified-sellers": "verify",
+    "scam-registry": "report",
+    "encrypted-data": "lock",
+    encryption: "lock",
+    tls: "lock",
+    rbac: "user",
+    "min-priv": "settings",
+};
+/**
+ * Resolve a stored icon string to a registry key.
+ *
+ * Accepts an already-valid `IconKey` unchanged, so a value authored after the
+ * admin editor moved to a key picker needs no alias entry.
+ */
+export function resolveTrustIcon(stored) {
+    if (!stored)
+        return undefined;
+    const aliased = TRUST_ICON_ALIASES[stored];
+    if (aliased)
+        return aliased;
+    return isIconKey(stored) ? stored : undefined;
+}

package/dist/features/homepage/lib/section-defaults.d.ts

@@ -1,11 +1,26 @@
 /** Static default content used when Firestore section config has no override. */
+import type { IconKey } from "../../../ui/icons/icon-registry";
+/**
+ * 🛑 `iconName` holds a real `IconKey`, not a slug.
+ *
+ * These used to carry intent slugs (`"secure-payments"`, `"fast-delivery"`…)
+ * that nothing resolved, because the component's only icon channel was a
+ * `renderIcon` function prop the section renderer never passed. The slugs are
+ * still accepted from STORED documents via `resolveTrustIcon`, but a default
+ * authored here has no reason to go through an alias — so these are typed.
+ *
+ * `id` is separate from `iconName` because the old shape used the icon string
+ * as the React key, which collides as soon as two tiles share a glyph.
+ */
 export declare const DEFAULT_TRUST_FEATURES: {
-    iconName: string;
+    id: string;
     title: string;
     description: string;
+    iconName?: IconKey;
 }[];
 export declare const DEFAULT_SECURITY_ITEMS: {
     key: string;
     title: string;
     description: string;
+    iconName?: IconKey;
 }[];

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

@@ -1,22 +1,38 @@
 /** Static default content used when Firestore section config has no override. */
+/**
+ * 🛑 `iconName` holds a real `IconKey`, not a slug.
+ *
+ * These used to carry intent slugs (`"secure-payments"`, `"fast-delivery"`…)
+ * that nothing resolved, because the component's only icon channel was a
+ * `renderIcon` function prop the section renderer never passed. The slugs are
+ * still accepted from STORED documents via `resolveTrustIcon`, but a default
+ * authored here has no reason to go through an alias — so these are typed.
+ *
+ * `id` is separate from `iconName` because the old shape used the icon string
+ * as the React key, which collides as soon as two tiles share a glyph.
+ */
 export const DEFAULT_TRUST_FEATURES = [
     {
-        iconName: "secure-payments",
+        id: "secure-payments",
+        iconName: "lock",
         title: "Secure Payments",
         description: "Protected payments with transparent order tracking.",
     },
     {
-        iconName: "fast-delivery",
+        id: "fast-delivery",
+        iconName: "ship",
         title: "Fast Delivery",
         description: "Fast shipping with reliable nationwide logistics partners.",
     },
     {
-        iconName: "easy-returns",
+        id: "easy-returns",
+        iconName: "restore",
         title: "Easy Returns",
         description: "Hassle-free returns within the policy window.",
     },
     {
-        iconName: "support",
+        id: "support",
+        iconName: "help",
         title: "24/7 Support",
         description: "Real help from our team across pre and post purchase.",
     },
@@ -24,21 +40,25 @@ export const DEFAULT_TRUST_FEATURES = [
 export const DEFAULT_SECURITY_ITEMS = [
     {
         key: "encryption",
+        iconName: "lock",
         title: "End-to-End Encryption",
         description: "All sensitive data is encrypted in transit and at rest.",
     },
     {
         key: "tls",
+        iconName: "verify",
         title: "TLS 1.3 in Transit",
         description: "Every API call and page load is secured with modern TLS.",
     },
     {
         key: "rbac",
+        iconName: "user",
         title: "Role-Based Access",
         description: "Strict role boundaries keep buyer, seller, and admin data separate.",
     },
     {
         key: "min-priv",
+        iconName: "settings",
         title: "Minimum-Privilege Tokens",
         description: "Short-lived, scoped tokens minimise exposure on every request.",
     },

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

@@ -5,6 +5,11 @@ import { cleanTitle, parseWelcomeDescription } from "./section-helpers.js";
 import { DEFAULT_TRUST_FEATURES, DEFAULT_SECURITY_ITEMS } from "./section-defaults.js";
 import { SECTION_TITLE, SECTION_COPY, VIEW_MORE_LABEL, WELCOME_TRUST_CHIPS, } from "../constants/section-copy.js";
 import { FAQ_CATEGORY_LABELS } from "../constants/faq-category-labels.js";
+/* Root Cause #51 — the stored `icon` string had no reader. These resolve it to
+   a registry key so the trust / security / stats tiles render a real glyph
+   instead of one hardcoded ✓ (or nothing at all). */
+import { resolveTrustIcon } from "../constants/trust-icon-aliases.js";
+import { STAT_PRESET_ICON } from "../constants/stat-icons.js";
 import { FAQ_HOMEPAGE_READ_CAP } from "../../faq/constants/read-caps.js";
 import { AnnouncementBar, hashBannerMessage } from "../components/AnnouncementBar.js";
 import { HeroCarousel } from "../components/HeroCarousel.js";
@@ -66,9 +71,26 @@ const SECTION_REGISTRY = {
     },
     welcome: {
         surfaces: ["homepage"],
-        render: ({ config, brand }) => {
+        render: ({ config, brand, sectionData }) => {
             const cfg = config;
-            return (_jsx(WelcomeSection, { title: cleanTitle(cfg?.h1) || SECTION_TITLE.welcome, 
+            /*
+             * Hero imagery, taken from the featured categories' own covers.
+             *
+             * Deterministic — the first five in CONFIGURED order, never shuffled, so
+             * the server and client render the same mosaic (ImageMosaic's header is
+             * explicit about why `Math.random()` is wrong here).
+             *
+             * 🛑 `sectionData.categories` is only populated when the page also has a
+             * `categories` section enabled, because MarketplaceHomepageView gates
+             * each fetch on `activeTypes`. `welcome` is registered as a trigger for
+             * that fetch for exactly this reason; without it the mosaic silently
+             * falls back to the brand panel and nothing says why.
+             */
+            const heroImages = (sectionData.categories ?? [])
+                .map((c) => c.display?.coverImage)
+                .filter((src) => Boolean(src))
+                .slice(0, 5);
+            return (_jsx(WelcomeSection, { heroImages: heroImages, 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 }));
@@ -103,6 +125,11 @@ const SECTION_REGISTRY = {
                             : `stat-${index}`,
                         label: item.label,
                         value: displayValue,
+                        // Derived from the preset, so a live stat gets a correct icon
+                        // with no extra config — the preset already says what the
+                        // number measures. `iconName` on the config entry wins for a
+                        // static stat, which has no metric to derive from.
+                        iconName: resolveTrustIcon(item.iconName) ?? (item.metric ? STAT_PRESET_ICON[item.metric] : undefined),
                     };
                 })
                 : [];
@@ -165,7 +192,7 @@ const SECTION_REGISTRY = {
             // 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 }));
+            return (_jsx(CTABannerSection, { title: cfg?.content?.title || SECTION_TITLE.banner, eyebrow: cfg?.content?.eyebrow || SECTION_COPY.bannerEyebrow, 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 }));
         },
     },
     "trust-indicators": {
@@ -175,8 +202,10 @@ const SECTION_REGISTRY = {
             const configured = (cfg?.indicators ?? [])
                 .filter((ind) => ind?.title?.trim())
                 .map((ind) => ({
-                key: ind.id,
-                iconName: ind.icon,
+                // `id` is the React key; `iconName` is the glyph. These were one
+                // field before, so two indicators sharing an icon collided.
+                id: ind.id,
+                iconName: resolveTrustIcon(ind.icon),
                 title: ind.title,
                 description: ind.description,
             }));
@@ -191,7 +220,13 @@ const SECTION_REGISTRY = {
             // `items` is the real shape; `features: string[]` is the legacy one and
             // becomes title-only cards. Neither reached the component before — it
             // always rendered DEFAULT_SECURITY_ITEMS regardless of config.
-            const configured = cfg?.items?.filter((item) => item?.title?.trim()) ??
+            const configured = cfg?.items
+                ?.filter((item) => item?.title?.trim())
+                // The stored `key` doubles as the icon hint — the seeded items carry
+                // intent slugs (`escrow`, `scam-registry`, `encrypted-data`) that the
+                // alias map resolves, so these tiles get real glyphs with no new
+                // config field. An explicit `iconName` wins when present.
+                .map((item) => ({ ...item, iconName: resolveTrustIcon(item.iconName ?? item.key) })) ??
                 cfg?.features
                     ?.filter((label) => label?.trim())
                     .map((label, index) => ({ key: `feature-${index}`, title: label, description: "" })) ??
@@ -206,7 +241,7 @@ const SECTION_REGISTRY = {
             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 }));
+                memberCount: cfg?.memberCount, groupLink: cfg?.groupLink || undefined, benefits: cfg?.benefits ?? [], testimonial: cfg?.testimonial, buttonText: cfg?.buttonText }));
         },
     },
     faq: {
@@ -331,7 +366,12 @@ const SECTION_REGISTRY = {
             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 }));
+            return (_jsx(HowItWorksSection, { title: cfg.title, subtitle: cfg.subtitle, pillLabel: cfg.pillLabel, ctaLabel: cfg.ctaLabel, ctaLink: cfg.ctaLink, 
+                /* `cfg.steps[].iconKey` is a loose `string` (it is admin data) while
+                   the component's is an `IconKey`. Resolving rather than casting
+                   means an unrecognised stored value renders a step with no icon
+                   instead of handing `<Icon>` a key it will silently drop. */
+                steps: cfg.steps.map((s) => ({ ...s, iconKey: resolveTrustIcon(s.iconKey) })) }));
         },
     },
     testimonials: {