@mohasinac/appkit 4.52.5 → 4.53.1

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

@@ -651,6 +651,12 @@ export interface EventRafflesSectionConfig {
     title?: string;
     subtitle?: string;
     maxItems?: number;
+    /**
+     * Which prize-event types the strip spans. The two concrete values are
+     * `EventType` members, matched against the `type` field — see
+     * `EventRafflesSection` for why `hasRaffle` was the wrong field and what it
+     * silently did instead.
+     */
     raffleType?: "raffle" | "spin_wheel" | "all";
     showEntryCount?: boolean;
     showCountdown?: boolean;
@@ -665,22 +671,125 @@ export interface GoogleReviewsSectionConfig {
     linkToGoogleMaps?: boolean;
     googleMapsUrl?: string;
 }
-export type SectionType = "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";
+/**
+ * Added 2026-10-19 promoting `HowItWorksSection` out of the orphan set — see
+ * `HowItWorksSection.tsx`'s own docstring for why `renderIcon`/`onCtaClick`
+ * (function props, not serialisable) became `iconKey`/`ctaLink`. `steps` is
+ * inline because the step count/order IS the authored content, same reasoning
+ * as `TestimonialsSectionConfig.testimonials` below.
+ */
+export interface HowItWorksStepConfig {
+    number: number;
+    title: string;
+    desc: string;
+    iconKey?: string;
+    iconColor?: string;
+    iconBg?: string;
+    badgeBg?: string;
+}
+export interface HowItWorksSectionConfig {
+    title: string;
+    subtitle?: string;
+    pillLabel?: string;
+    ctaLabel?: string;
+    ctaLink?: string;
+    steps: HowItWorksStepConfig[];
+}
+/**
+ * Added 2026-10-19 promoting `TestimonialsCarousel` out of the orphan set.
+ * Deliberately NOT a read from the `testimonials` collection shape
+ * (`Testimonial` in `types/index.ts`) — `featured`/`sortOrder`/`active` are
+ * collection-row housekeeping with no meaning inside an already-ordered
+ * config array, and `avatarUrl` was declared there and never rendered. No
+ * `autoScroll`/`scrollInterval`/`loop` either: the component has no autoplay,
+ * arrows or dots — it is not actually a carousel, despite the name.
+ */
+/** An embedded sub-document with its own `id` — a type alias, not a Firestore collection root, so it does not extend `BaseDocument`. */
+export type TestimonialConfigEntry = {
+    id: string;
+    name: string;
+    rating: 1 | 2 | 3 | 4 | 5;
+    text: string;
+};
+export interface TestimonialsSectionConfig {
+    eyebrow?: string;
+    heading?: string;
+    testimonials: TestimonialConfigEntry[];
+}
+/**
+ * Added 2026-10-19 promoting `PromoGrid` out of the orphan set. `banners` is
+ * capped at `PROMO_GRID_MAX_BANNERS` (4) by the component itself — the
+ * layout has exactly one hero slot and three regular ones, so a 5th banner
+ * is silently dropped, not a bug. No admin background/colour field: the dark
+ * theme is intentionally hardcoded (Root Cause #67 — a themed background
+ * paired with fixed white ink would invert wrong in a light theme; this
+ * component is always dark, by design, so it never pairs the two).
+ */
+/** An embedded sub-document with its own `id` — a type alias, not a Firestore collection root, so it does not extend `BaseDocument`. */
+export type PromoBannerConfigEntry = {
+    id: string;
+    title: string;
+    ctaLabel: string;
+    ctaUrl: string;
+    image: string;
+};
+export interface PromoGridSectionConfig {
+    eyebrow?: string;
+    heading?: string;
+    banners: PromoBannerConfigEntry[];
+}
+export type SectionType = "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" | "how-it-works" | "testimonials" | "promo-grid";
 export type SectionConfig = CarouselSectionConfig | WelcomeSectionConfig | StatsSectionConfig | TrustIndicatorsSectionConfig | CategoriesSectionConfig | BrandsSectionConfig | ProductsSectionConfig | PreOrdersSectionConfig | AuctionsSectionConfig | BannerSectionConfig | FeaturesSectionConfig | ReviewsSectionConfig | WhatsAppCommunitySectionConfig | FAQSectionConfig | BlogArticlesSectionConfig | NewsletterSectionConfig | StoresSectionConfig | EventsSectionConfig | SocialFeedSectionConfig | CustomCardsSectionConfig | GoogleReviewsSectionConfig | FeaturedBundlesSectionConfig | PrizeDrawsSectionConfig | EventRafflesSectionConfig | CollectionCardsSectionConfig;
+/**
+ * Which page a section row belongs to.
+ *
+ * One collection, one owner per surface. This does NOT reintroduce the
+ * `siteSettings.homepageLayout` that `sectionTemplates.ts` deliberately refuses
+ * — that note forbids a SECOND owner of the homepage's layout, and this keeps
+ * `homepageSections` the single source of truth while letting a category or a
+ * brand page own its own ordered list.
+ */
+export declare const SECTION_SURFACE_VALUES: readonly ["homepage", "category", "brand", "product", "store"];
+export type SectionSurface = (typeof SECTION_SURFACE_VALUES)[number];
+/** Absent means `"homepage"`. See the field comment below. */
+export declare const DEFAULT_SECTION_SURFACE: SectionSurface;
 export interface HomepageSectionDocument extends BaseDocument {
     type: SectionType;
     order: number;
     enabled: boolean;
     config: SectionConfig;
+    /**
+     * 🛑 OPTIONAL, and that is load-bearing. Every other field on this document
+     * is required, so a non-optional `surface` would make every one of the 23
+     * existing rows fail the type on read. Absent therefore means
+     * `DEFAULT_SECTION_SURFACE` — which is also the honest reading of history,
+     * since every row written before this existed was a homepage row.
+     *
+     * 🛑 Filter it IN MEMORY, never as a Firestore clause. The only composite
+     * index on this collection is `(enabled, order)`;
+     * `where(enabled).where(surface).orderBy(order)` is a three-field composite
+     * it does not cover and Firestore throws FAILED_PRECONDITION at RUNTIME, not
+     * at build time. `MarketplaceHomepageView` already filters sections in memory
+     * for the listing-type gate — follow that precedent. Section counts are tens.
+     */
+    surface?: SectionSurface;
 }
 export declare const HOMEPAGE_SECTIONS_COLLECTION: "homepageSections";
 export declare const HOMEPAGE_SECTIONS_INDEXED_FIELDS: readonly ["enabled", "order", "type"];
 export declare const DEFAULT_SECTION_ORDER: Record<SectionType, number>;
 export declare const BANNER_HEIGHTS: Record<BannerSectionConfig["height"], string>;
 export type HomepageSectionCreateInput = Omit<HomepageSectionDocument, "id" | "createdAt" | "updatedAt">;
-export type HomepageSectionUpdateInput = Partial<Pick<HomepageSectionDocument, "order" | "enabled" | "config">>;
+export type HomepageSectionUpdateInput = Partial<Pick<HomepageSectionDocument, "order" | "enabled" | "config" | "surface">>;
 export declare const homepageSectionQueryHelpers: {
     readonly enabled: () => readonly ["enabled", "==", true];
     readonly byType: (type: SectionType) => readonly ["type", "==", SectionType];
 };
-export declare function createHomepageSectionId(type: SectionType): string;
+/**
+ * 🛑 The surface is part of the id, or a category's `products` section collides
+ * with the homepage's — same type, same generated slug, one document.
+ *
+ * `"homepage"` is omitted from the id so every existing row keeps the exact id
+ * it already has. A migration here would be a rename of 23 live documents to
+ * gain nothing.
+ */
+export declare function createHomepageSectionId(type: SectionType, surface?: SectionSurface): string;

package/dist/features/homepage/schemas/firestore.js

@@ -67,6 +67,24 @@ export const ALLOWED_LIVE_COLLECTIONS = [
     "bids",
 ];
 export const COLLECTION_CARDS_MAX_ENTRIES = 3;
+/**
+ * Which page a section row belongs to.
+ *
+ * One collection, one owner per surface. This does NOT reintroduce the
+ * `siteSettings.homepageLayout` that `sectionTemplates.ts` deliberately refuses
+ * — that note forbids a SECOND owner of the homepage's layout, and this keeps
+ * `homepageSections` the single source of truth while letting a category or a
+ * brand page own its own ordered list.
+ */
+export const SECTION_SURFACE_VALUES = [
+    "homepage",
+    "category",
+    "brand",
+    "product",
+    "store",
+];
+/** Absent means `"homepage"`. See the field comment below. */
+export const DEFAULT_SECTION_SURFACE = "homepage";
 export const HOMEPAGE_SECTIONS_COLLECTION = "homepageSections";
 export const HOMEPAGE_SECTIONS_INDEXED_FIELDS = [
     "enabled",
@@ -99,6 +117,9 @@ export const DEFAULT_SECTION_ORDER = {
     "prize-draws": 21,
     "event-raffles": 22,
     "collection-cards": 23,
+    "how-it-works": 24,
+    testimonials: 25,
+    "promo-grid": 26,
 };
 export const BANNER_HEIGHTS = {
     sm: "200px",
@@ -110,6 +131,15 @@ export const homepageSectionQueryHelpers = {
     enabled: () => ["enabled", "==", true],
     byType: (type) => ["type", "==", type],
 };
-export function createHomepageSectionId(type) {
-    return generateHomepageSectionId({ type });
+/**
+ * 🛑 The surface is part of the id, or a category's `products` section collides
+ * with the homepage's — same type, same generated slug, one document.
+ *
+ * `"homepage"` is omitted from the id so every existing row keeps the exact id
+ * it already has. A migration here would be a rename of 23 live documents to
+ * gain nothing.
+ */
+export function createHomepageSectionId(type, surface = DEFAULT_SECTION_SURFACE) {
+    const base = generateHomepageSectionId({ type });
+    return surface === DEFAULT_SECTION_SURFACE ? base : `${base}-${surface}`;
 }

package/dist/features/homepage/schemas/index.d.ts

@@ -1,7 +1,32 @@
 export * from "./firestore";
 import { z } from "zod";
+import type { SectionType } from "./firestore";
 import type { JsonValue } from "../../../schemas/types";
-export declare const homepageSectionTypeSchema: 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"]>;
+/**
+ * 🛑 GENUINELY derived from `SectionType`, not a parallel hand-written list.
+ *
+ * This used to be a literal `z.enum([...25 strings...])`, with a docstring one
+ * screen up claiming it was "derived from the union, so that gap cannot
+ * reopen." It was not derived — it was a hand-typed duplicate that happened to
+ * agree with `SectionType` on the day it was written, with nothing enforcing
+ * that agreement afterward. Adding a 26th section type without also editing
+ * this array would 400 every save of the new type — exactly the failure the
+ * docstring claimed was already closed.
+ *
+ * `DEFAULT_SECTION_ORDER: Record<SectionType, number>` (`./firestore.ts`) is
+ * already compile-checked exhaustive over `SectionType` — TypeScript refuses
+ * to compile it if a union member is missing a key, or if an extra key exists
+ * that isn't in the union. So `Object.keys(DEFAULT_SECTION_ORDER)` IS the
+ * `SectionType` value set, genuinely, every time this file is built — adding
+ * a type to the union without updating `DEFAULT_SECTION_ORDER` is now a `tsc`
+ * error at THAT assignment, not a runtime 400 discovered on save.
+ *
+ * The cast is sound, not a loosening: `Object.keys` returns `string[]` only
+ * because that's TypeScript's (overly conservative) built-in signature for
+ * it — the compile-time guarantee from `DEFAULT_SECTION_ORDER`'s own type
+ * is what actually makes the runtime values correct.
+ */
+export declare const homepageSectionTypeSchema: z.ZodEnum<[SectionType, ...SectionType[]]>;
 export declare const homepageSectionFirestoreSchema: z.ZodObject<{
     createdAt: z.ZodUnion<[z.ZodDate, z.ZodString, z.ZodObject<{
         toDate: z.ZodFunction<z.ZodTuple<[], z.ZodUnknown>, z.ZodDate>;
@@ -18,12 +43,12 @@ export declare const homepageSectionFirestoreSchema: z.ZodObject<{
         toDate: z.ZodFunction<z.ZodTuple<[], z.ZodUnknown>, z.ZodDate>;
     }, z.ZodTypeAny, "passthrough">>]>;
     id: z.ZodString;
-    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<[SectionType, ...SectionType[]]>;
     order: z.ZodNumber;
     enabled: z.ZodBoolean;
     config: z.ZodRecord<z.ZodString, z.ZodType<JsonValue, z.ZodTypeDef, JsonValue>>;
 }, "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: SectionType;
     id: string;
     createdAt: string | Date | z.objectOutputType<{
         toDate: z.ZodFunction<z.ZodTuple<[], z.ZodUnknown>, z.ZodDate>;
@@ -35,7 +60,7 @@ export declare const homepageSectionFirestoreSchema: z.ZodObject<{
     order: number;
     config: Record<string, JsonValue>;
 }, {
-    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: SectionType;
     id: string;
     createdAt: string | Date | z.objectInputType<{
         toDate: z.ZodFunction<z.ZodTuple<[], z.ZodUnknown>, z.ZodDate>;
@@ -61,19 +86,23 @@ export declare const homepageSectionFirestoreSchema: z.ZodObject<{
  * `type` comes from `homepageSectionTypeSchema`, which is derived from the
  * union, so that gap cannot reopen.
  */
+export declare const sectionSurfaceSchema: z.ZodEnum<["homepage", "category", "brand", "product", "store"]>;
 export declare const homepageSectionCreateSchema: 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<[SectionType, ...SectionType[]]>;
     enabled: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
     order: z.ZodOptional<z.ZodNumber>;
+    surface: z.ZodOptional<z.ZodEnum<["homepage", "category", "brand", "product", "store"]>>;
     config: z.ZodRecord<z.ZodString, z.ZodType<JsonValue, z.ZodTypeDef, JsonValue>>;
 }, "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: SectionType;
     enabled: boolean;
     config: Record<string, JsonValue>;
+    surface?: "brand" | "category" | "store" | "product" | "homepage" | undefined;
     order?: number | 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: SectionType;
     config: Record<string, JsonValue>;
+    surface?: "brand" | "category" | "store" | "product" | "homepage" | undefined;
     enabled?: boolean | undefined;
     order?: number | undefined;
 }>;
@@ -184,15 +213,15 @@ export declare const carouselCardSchema: z.ZodObject<{
     }, "strip", z.ZodTypeAny, {
         title?: string | undefined;
         description?: string | undefined;
-        textAlign?: "center" | "left" | "right" | undefined;
         textColor?: string | undefined;
+        textAlign?: "center" | "left" | "right" | undefined;
         subtitle?: string | undefined;
         eyebrow?: string | undefined;
     }, {
         title?: string | undefined;
         description?: string | undefined;
-        textAlign?: "center" | "left" | "right" | undefined;
         textColor?: string | undefined;
+        textAlign?: "center" | "left" | "right" | undefined;
         subtitle?: string | undefined;
         eyebrow?: string | undefined;
     }>>;
@@ -251,8 +280,8 @@ export declare const carouselCardSchema: z.ZodObject<{
     content?: {
         title?: string | undefined;
         description?: string | undefined;
-        textAlign?: "center" | "left" | "right" | undefined;
         textColor?: string | undefined;
+        textAlign?: "center" | "left" | "right" | undefined;
         subtitle?: string | undefined;
         eyebrow?: string | undefined;
     } | undefined;
@@ -292,8 +321,8 @@ export declare const carouselCardSchema: z.ZodObject<{
     content?: {
         title?: string | undefined;
         description?: string | undefined;
-        textAlign?: "center" | "left" | "right" | undefined;
         textColor?: string | undefined;
+        textAlign?: "center" | "left" | "right" | undefined;
         subtitle?: string | undefined;
         eyebrow?: string | undefined;
     } | undefined;
@@ -524,15 +553,15 @@ export declare const carouselSlideFirestoreSchema: z.ZodObject<{
         }, "strip", z.ZodTypeAny, {
             title?: string | undefined;
             description?: string | undefined;
-            textAlign?: "center" | "left" | "right" | undefined;
             textColor?: string | undefined;
+            textAlign?: "center" | "left" | "right" | undefined;
             subtitle?: string | undefined;
             eyebrow?: string | undefined;
         }, {
             title?: string | undefined;
             description?: string | undefined;
-            textAlign?: "center" | "left" | "right" | undefined;
             textColor?: string | undefined;
+            textAlign?: "center" | "left" | "right" | undefined;
             subtitle?: string | undefined;
             eyebrow?: string | undefined;
         }>>;
@@ -591,8 +620,8 @@ export declare const carouselSlideFirestoreSchema: z.ZodObject<{
         content?: {
             title?: string | undefined;
             description?: string | undefined;
-            textAlign?: "center" | "left" | "right" | undefined;
             textColor?: string | undefined;
+            textAlign?: "center" | "left" | "right" | undefined;
             subtitle?: string | undefined;
             eyebrow?: string | undefined;
         } | undefined;
@@ -632,8 +661,8 @@ export declare const carouselSlideFirestoreSchema: z.ZodObject<{
         content?: {
             title?: string | undefined;
             description?: string | undefined;
-            textAlign?: "center" | "left" | "right" | undefined;
             textColor?: string | undefined;
+            textAlign?: "center" | "left" | "right" | undefined;
             subtitle?: string | undefined;
             eyebrow?: string | undefined;
         } | undefined;
@@ -771,8 +800,8 @@ export declare const carouselSlideFirestoreSchema: z.ZodObject<{
         content?: {
             title?: string | undefined;
             description?: string | undefined;
-            textAlign?: "center" | "left" | "right" | undefined;
             textColor?: string | undefined;
+            textAlign?: "center" | "left" | "right" | undefined;
             subtitle?: string | undefined;
             eyebrow?: string | undefined;
         } | undefined;
@@ -880,8 +909,8 @@ export declare const carouselSlideFirestoreSchema: z.ZodObject<{
         content?: {
             title?: string | undefined;
             description?: string | undefined;
-            textAlign?: "center" | "left" | "right" | undefined;
             textColor?: string | undefined;
+            textAlign?: "center" | "left" | "right" | undefined;
             subtitle?: string | undefined;
             eyebrow?: string | undefined;
         } | undefined;

package/dist/features/homepage/schemas/index.js

@@ -10,34 +10,33 @@ export * from "./firestore.js";
 // Here the `config` field is treated as a typed `Record<string, JsonValue>` —
 // the section-builder schemas validate it at the form boundary.
 import { z } from "zod";
+import { DEFAULT_SECTION_ORDER, SECTION_SURFACE_VALUES } from "./firestore.js";
 import { auditTimestampsShape, firestoreDateSchema } from "../../../schemas/firestore-helpers.js";
-export const homepageSectionTypeSchema = z.enum([
-    "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",
-]);
+/**
+ * 🛑 GENUINELY derived from `SectionType`, not a parallel hand-written list.
+ *
+ * This used to be a literal `z.enum([...25 strings...])`, with a docstring one
+ * screen up claiming it was "derived from the union, so that gap cannot
+ * reopen." It was not derived — it was a hand-typed duplicate that happened to
+ * agree with `SectionType` on the day it was written, with nothing enforcing
+ * that agreement afterward. Adding a 26th section type without also editing
+ * this array would 400 every save of the new type — exactly the failure the
+ * docstring claimed was already closed.
+ *
+ * `DEFAULT_SECTION_ORDER: Record<SectionType, number>` (`./firestore.ts`) is
+ * already compile-checked exhaustive over `SectionType` — TypeScript refuses
+ * to compile it if a union member is missing a key, or if an extra key exists
+ * that isn't in the union. So `Object.keys(DEFAULT_SECTION_ORDER)` IS the
+ * `SectionType` value set, genuinely, every time this file is built — adding
+ * a type to the union without updating `DEFAULT_SECTION_ORDER` is now a `tsc`
+ * error at THAT assignment, not a runtime 400 discovered on save.
+ *
+ * The cast is sound, not a loosening: `Object.keys` returns `string[]` only
+ * because that's TypeScript's (overly conservative) built-in signature for
+ * it — the compile-time guarantee from `DEFAULT_SECTION_ORDER`'s own type
+ * is what actually makes the runtime values correct.
+ */
+export const homepageSectionTypeSchema = z.enum(Object.keys(DEFAULT_SECTION_ORDER));
 // JsonValue Zod — used for section configs whose shape varies per section type.
 // The section-builder schemas (W5 row 1) provide the per-type validation.
 const jsonValueSchema = z.lazy(() => z.union([
@@ -70,10 +69,23 @@ export const homepageSectionFirestoreSchema = z.object({
  * `type` comes from `homepageSectionTypeSchema`, which is derived from the
  * union, so that gap cannot reopen.
  */
+/*
+ * 🛑 Derived from SECTION_SURFACE_VALUES, not restated as a literal list —
+ * same discipline `homepageSectionTypeSchema` above now follows too (fixed
+ * 2026-10-19; it used to be the hand-written duplicate this comment used to
+ * warn about, with nothing enforcing parity with `SectionType`).
+ */
+export const sectionSurfaceSchema = z.enum(SECTION_SURFACE_VALUES);
 export const homepageSectionCreateSchema = z.object({
     type: homepageSectionTypeSchema,
     enabled: z.boolean().optional().default(true),
     order: z.number().int().optional(),
+    /*
+     * A plain `z.object()` STRIPS unknown keys silently, so without this line a
+     * caller's `surface` vanishes between the request and the handler with no
+     * error anywhere — Root Cause #76. Absent still means "homepage".
+     */
+    surface: sectionSurfaceSchema.optional(),
     // Deliberately open. Every section type carries a different config shape,
     // and a closed schema here would silently STRIP the builder's output for any
     // type it did not enumerate — the `productBaseSchema` failure, one domain

package/dist/features/homepage/server.d.ts

@@ -1,9 +1,6 @@
 export * from "./actions";
-export { HomepageSectionsRepository } from "./repository/homepage.repository";
 export { carouselRepository } from "./repository/carousel.repository";
 export { homepageSectionsRepository } from "./repository/homepage-sections.repository";
 export { manifest } from "./manifest";
-export { GET as homepageGET, GET, POST } from "./api/route";
-export { homepageSectionItemGET, homepageSectionItemPATCH, homepageSectionItemDELETE, } from "./api/[id]/route";
 export { carouselGET, carouselPOST } from "./api/carousel/route";
 export { carouselItemGET, carouselItemPATCH, carouselItemDELETE, } from "./api/carousel/[id]/route";

package/dist/features/homepage/server.js

@@ -1,9 +1,6 @@
 export * from "./actions/index.js";
-export { HomepageSectionsRepository } from "./repository/homepage.repository.js";
 export { carouselRepository } from "./repository/carousel.repository.js";
 export { homepageSectionsRepository } from "./repository/homepage-sections.repository.js";
 export { manifest } from "./manifest.js";
-export { GET as homepageGET, GET, POST } from "./api/route.js";
-export { homepageSectionItemGET, homepageSectionItemPATCH, homepageSectionItemDELETE, } from "./api/[id]/route.js";
 export { carouselGET, carouselPOST } from "./api/carousel/route.js";
 export { carouselItemGET, carouselItemPATCH, carouselItemDELETE, } from "./api/carousel/[id]/route.js";

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

@@ -1,31 +1,3 @@
-export type HomepageSectionType = "hero" | "featured_categories" | "featured_products" | "banner" | "testimonials" | "promotions" | "blog_posts" | "sellers" | "custom";
-export interface HomepageSectionContent {
-    title?: string;
-    subtitle?: string;
-    ctaLabel?: string;
-    ctaUrl?: string;
-    imageUrl?: string;
-    videoUrl?: string;
-    itemIds?: string[];
-    html?: string;
-}
-export interface HomepageSection {
-    id: string;
-    type: HomepageSectionType;
-    title?: string;
-    /** Primary enable/disable flag stored in Firestore as `enabled` */
-    enabled?: boolean;
-    /** Alias kept for older consumers */
-    isVisible?: boolean;
-    order?: number;
-    content?: HomepageSectionContent;
-    mobile?: Partial<HomepageSectionContent>;
-    createdAt?: string;
-    updatedAt?: string;
-}
-export interface HomepageData {
-    sections: HomepageSection[];
-}
 export interface HotspotPin {
     id: string;
     name: string;
@@ -62,15 +34,6 @@ export interface Banner {
     sortOrder: number;
     active: boolean;
 }
-export interface PromoBanner {
-    id: string;
-    title: string;
-    ctaLabel: string;
-    ctaUrl: string;
-    image: string;
-    sortOrder: number;
-    active: boolean;
-}
 export type TrustBadgeIconKey = "shipping" | "support" | "rewards" | "secure";
 export interface TrustBadge {
     id: string;
@@ -80,16 +43,6 @@ export interface TrustBadge {
     sortOrder: number;
     active: boolean;
 }
-export interface Testimonial {
-    id: string;
-    name: string;
-    rating: 1 | 2 | 3 | 4 | 5;
-    text: string;
-    avatarUrl?: string;
-    featured: boolean;
-    sortOrder: number;
-    active: boolean;
-}
 export interface BeforeAfterItem {
     id: string;
     beforeImage: string;

package/dist/features/homepage/types/index.js

@@ -1 +1,50 @@
+/*
+ * 🛑 DELETED 2026-10-19 — a second, incompatible section vocabulary, attached
+ * to LIVE, MOUNTED, publicly-reachable code.
+ *
+ * This file declared `HomepageSectionType` (9 values: `hero`,
+ * `featured_categories`, `featured_products`, `banner`, `testimonials`,
+ * `promotions`, `blog_posts`, `sellers`, `custom`), `HomepageSectionContent`,
+ * `HomepageSection` and `HomepageData`, against the live `SectionType` in
+ * `../schemas/firestore.ts`, which holds 25 values sharing exactly ONE
+ * (`banner`) with this union. A second, independently-declared copy of the
+ * same 9-value union lived in `seed/factories/homepage-section.factory.ts`
+ * too — THREE incompatible section vocabularies in one codebase, none of them
+ * the one the real renderer and repository use.
+ *
+ * This was not dead code sitting unused — `GET /api/homepage-sections` and
+ * `GET/POST /api/homepage-sections/[id]` were REAL, MOUNTED routes (stubs
+ * literally headed "feat-homepage — Pure stub", from a generic starter kit
+ * never adapted to this project) reading/writing the SAME `homepageSections`
+ * Firestore collection the real system owns, through a SECOND,
+ * identically-named `HomepageSectionsRepository` class (a generic
+ * `IRepository<HomepageSection>` wrapper in `repository/homepage.repository.ts`,
+ * distinct from the real `BaseRepository`-backed one in
+ * `homepage-sections.repository.ts`) — Root Cause #36's two-same-named-types
+ * defect, on a REPOSITORY CLASS this time, with a live route behind it.
+ *
+ * Concretely, before this deletion: the stub's GET filtered on `isVisible==true`,
+ * a field that does not exist on a real `HomepageSectionDocument` (the real
+ * field is `enabled`), so unauthenticated requests always got `[]`; its POST
+ * (admin-gated) would have written a document shaped `{ type: "hero", title,
+ * content: {...} }` into the collection the real renderer reads, where
+ * `SECTION_REGISTRY[section.type]` — see `../lib/section-renderer.tsx` — would
+ * resolve to `undefined` and render nothing, with no error anywhere: a
+ * corrupted, uneditable-through-the-real-admin-UI row, silently invisible.
+ *
+ * `useHomepage()` (the hook typed against `HomepageData`) fetched
+ * `HOMEPAGE_ENDPOINTS.GET = "/api/homepage"`, which was never mounted at all.
+ * `useHomepageSections()` called the stub above and had zero real callers —
+ * only a comment in `AdminSectionsView.tsx` mentioning it existed.
+ *
+ * All of it is deleted: the two hooks, the stub API routes (`api/route.ts`,
+ * `api/[id]/`, and a THIRD unused parallel stub at `api/sections/` for
+ * `/api/homepage/sections`), the stub repository class, `HeroSection.tsx`
+ * (zero real consumers), the seed factory, and the matching consumer-side
+ * `src/app/api/homepage-sections/{route.ts,[id]/route.ts}`.
+ *
+ * The live contract is `SectionType` / `SectionConfig` / `HomepageSectionDocument`
+ * in `../schemas/firestore.ts`, served by `GET /api/admin/sections` and read
+ * directly by `MarketplaceHomepageView` via `homepageSectionsRepository`.
+ */
 export {};

package/dist/features/layout/AppLayoutShell.d.ts

@@ -8,6 +8,17 @@ export interface AppLayoutShellSidebarLink {
     label: string;
     /** Optional icon rendered before the label (emoji string or ReactNode). */
     icon?: React.ReactNode;
+    /**
+     * Sub-links, rendered indented beneath this one.
+     *
+     * 🛑 This mirrors the top navbar's dropdown, and it exists for the same
+     * reason the navbar's does: the sidebar and the mobile sheet are built from
+     * the SAME nav items, so a parent that gained children in the navbar would
+     * otherwise silently lose every one of them here — the merge would read as a
+     * deletion on exactly the surface phones use. One level only, matching
+     * `NavbarLayoutItem`.
+     */
+    children?: AppLayoutShellSidebarLink[];
 }
 export interface AppLayoutShellSidebarSection {
     title?: string;