@mohasinac/appkit 4.53.0 → 4.53.1

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

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

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

@@ -671,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;
 }>;

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.js

@@ -176,7 +176,7 @@ function SidebarContent({ sidebarItems, sidebarSections, sidebarPrimaryActions,
                         action.variant === "outline"
                             ? "border hover:bg-surface-hover border-[var(--appkit-color-border)] text-[var(--appkit-color-text)]"
                             : "bg-primary text-white hover:bg-primary-600 dark:bg-primary dark:hover:bg-primary-600 btn-glow",
-                    ].join(" "), children: action.label }, `${action.href}-${action.label}`))) })), isAuthenticated && (_jsx(CollapsibleNavGroup, { title: labels.sectionTitle, hasActive: !!activeProfileLink, children: _jsxs(Ul, { spacing: "2xs", children: [_jsx(Li, { children: _jsx(TextLink, { href: profileHref, variant: "none", className: activeProfileLink?.href === profileHref ? navItemActiveClass : navItemClass, "aria-current": activeProfileLink?.href === profileHref ? "page" : undefined, children: labels.profile }) }), userOrdersHref && (_jsx(Li, { children: _jsx(TextLink, { href: userOrdersHref, variant: "none", className: activeProfileLink?.href === userOrdersHref ? navItemActiveClass : navItemClass, "aria-current": activeProfileLink?.href === userOrdersHref ? "page" : undefined, children: labels.orders }) })), userWishlistHref && (_jsx(Li, { children: _jsx(TextLink, { href: userWishlistHref, variant: "none", className: activeProfileLink?.href === userWishlistHref ? navItemActiveClass : navItemClass, "aria-current": activeProfileLink?.href === userWishlistHref ? "page" : undefined, children: labels.wishlist }) })), userSettingsHref && (_jsx(Li, { children: _jsx(TextLink, { href: userSettingsHref, variant: "none", className: activeProfileLink?.href === userSettingsHref ? navItemActiveClass : navItemClass, "aria-current": activeProfileLink?.href === userSettingsHref ? "page" : undefined, children: labels.settings }) }))] }) })), isAuthenticated && user?.stats && (_jsxs(Div, { layout: "grid", gap: "2", className: "grid-cols-2", children: [user.stats.totalOrders != null && (_jsxs(Div, { className: CLS_STAT_BOX, children: [_jsx(Text, { className: "leading-none", color: "primary", size: "lg", weight: "bold", children: user.stats.totalOrders }), _jsx(Text, { className: CLS_STAT_LABEL, children: "Orders" })] })), user.stats.reviewsCount != null && (_jsxs(Div, { className: CLS_STAT_BOX, children: [_jsx(Text, { className: "leading-none", color: "primary", size: "lg", weight: "bold", children: user.stats.reviewsCount }), _jsx(Text, { className: CLS_STAT_LABEL, children: "Reviews" })] })), user.stats.auctionsWon != null && (_jsxs(Div, { className: CLS_STAT_BOX, children: [_jsx(Text, { className: "leading-none", color: "primary", size: "lg", weight: "bold", children: user.stats.auctionsWon }), _jsx(Text, { className: CLS_STAT_LABEL, children: "Auctions Won" })] })), user.stats.itemsSold != null && (_jsxs(Div, { className: CLS_STAT_BOX, children: [_jsx(Text, { className: "leading-none", color: "primary", size: "lg", weight: "bold", children: user.stats.itemsSold }), _jsx(Text, { className: CLS_STAT_LABEL, children: "Items Sold" })] }))] })), isAuthenticated && isAdminOrSeller && (adminHref || resolvedStoreHref) && (_jsx(CollapsibleNavGroup, { title: labels.dashboardSectionTitle, hasActive: !!activeDashboardLink, children: _jsxs(Ul, { spacing: "2xs", children: [adminHref && role === "admin" && (_jsx(Li, { children: _jsx(TextLink, { href: adminHref, variant: "none", className: activeDashboardLink?.href === adminHref ? navItemActiveClass : navItemClass, "aria-current": activeDashboardLink?.href === adminHref ? "page" : undefined, children: labels.adminDashboard }) })), resolvedStoreHref && isAdminOrSeller && (_jsx(Li, { children: _jsx(TextLink, { href: resolvedStoreHref, variant: "none", className: activeDashboardLink?.href === resolvedStoreHref ? navItemActiveClass : navItemClass, "aria-current": activeDashboardLink?.href === resolvedStoreHref ? "page" : undefined, children: labels.storeDashboard }) }))] }) })), normalizedSections.map((section, sectionIndex) => (_jsx(CollapsibleSidebarSection, { section: section, navItemClass: navItemClass, navItemActiveClass: navItemActiveClass, activeHref: activeHref }, `sidebar-section-${sectionIndex}`))), (sidebarLocaleSlot || showThemeToggleInSidebar || (isAuthenticated && onLogout)) && (_jsxs(Stack, { border: "default", className: "border-t border-[var(--appkit-color-border-subtle)]", padding: "t-md", gap: "3", children: [sidebarLocaleSlot, showThemeToggleInSidebar && (_jsxs("button", { type: "button", onClick: toggleTheme, className: "flex w-full items-center justify-end gap-[var(--appkit-space-3)] rounded-lg px-[var(--appkit-space-3)] py-[var(--appkit-space-2)] text-[length:var(--appkit-text-sm)] text-[var(--appkit-color-text-muted)] transition-colors hover:bg-primary-surface hover:text-primary-800", children: [_jsx(Span, { "aria-hidden": "true", children: theme === "dark" ? "☀️" : "🌙" }), activeThemeName] })), isAuthenticated && onLogout && (_jsx("button", { type: "button", onClick: () => { onLogout(); onAfterLogout(); }, className: CLS_LOGOUT_BTN, children: labels.logout }))] }))] }));
+                    ].join(" "), children: action.label }, `${action.href}-${action.label}`))) })), isAuthenticated && (_jsx(CollapsibleNavGroup, { title: labels.sectionTitle, hasActive: !!activeProfileLink, children: _jsxs(Ul, { spacing: "2xs", children: [_jsx(Li, { children: _jsx(TextLink, { href: profileHref, variant: "none", className: activeProfileLink?.href === profileHref ? navItemActiveClass : navItemClass, "aria-current": activeProfileLink?.href === profileHref ? "page" : undefined, children: labels.profile }) }), userOrdersHref && (_jsx(Li, { children: _jsx(TextLink, { href: userOrdersHref, variant: "none", className: activeProfileLink?.href === userOrdersHref ? navItemActiveClass : navItemClass, "aria-current": activeProfileLink?.href === userOrdersHref ? "page" : undefined, children: labels.orders }) })), userWishlistHref && (_jsx(Li, { children: _jsx(TextLink, { href: userWishlistHref, variant: "none", className: activeProfileLink?.href === userWishlistHref ? navItemActiveClass : navItemClass, "aria-current": activeProfileLink?.href === userWishlistHref ? "page" : undefined, children: labels.wishlist }) })), userSettingsHref && (_jsx(Li, { children: _jsx(TextLink, { href: userSettingsHref, variant: "none", className: activeProfileLink?.href === userSettingsHref ? navItemActiveClass : navItemClass, "aria-current": activeProfileLink?.href === userSettingsHref ? "page" : undefined, children: labels.settings }) }))] }) })), isAuthenticated && user?.stats && (_jsxs(Div, { layout: "grid", gap: "2", className: "grid-cols-2", children: [user.stats.totalOrders != null && (_jsxs(Div, { className: CLS_STAT_BOX, children: [_jsx(Text, { className: "leading-none", color: "primary", size: "lg", weight: "bold", children: user.stats.totalOrders }), _jsx(Text, { className: CLS_STAT_LABEL, children: "Orders" })] })), user.stats.reviewsCount != null && (_jsxs(Div, { className: CLS_STAT_BOX, children: [_jsx(Text, { className: "leading-none", color: "primary", size: "lg", weight: "bold", children: user.stats.reviewsCount }), _jsx(Text, { className: CLS_STAT_LABEL, children: "Reviews" })] })), user.stats.auctionsWon != null && (_jsxs(Div, { className: CLS_STAT_BOX, children: [_jsx(Text, { className: "leading-none", color: "primary", size: "lg", weight: "bold", children: user.stats.auctionsWon }), _jsx(Text, { className: CLS_STAT_LABEL, children: "Auctions Won" })] })), user.stats.itemsSold != null && (_jsxs(Div, { className: CLS_STAT_BOX, children: [_jsx(Text, { className: "leading-none", color: "primary", size: "lg", weight: "bold", children: user.stats.itemsSold }), _jsx(Text, { className: CLS_STAT_LABEL, children: "Items Sold" })] }))] })), isAuthenticated && isAdminOrSeller && (adminHref || resolvedStoreHref) && (_jsx(CollapsibleNavGroup, { title: labels.dashboardSectionTitle, hasActive: !!activeDashboardLink, children: _jsxs(Ul, { spacing: "2xs", children: [adminHref && role === "admin" && (_jsx(Li, { children: _jsx(TextLink, { href: adminHref, variant: "none", className: activeDashboardLink?.href === adminHref ? navItemActiveClass : navItemClass, "aria-current": activeDashboardLink?.href === adminHref ? "page" : undefined, children: labels.adminDashboard }) })), resolvedStoreHref && isAdminOrSeller && (_jsx(Li, { children: _jsx(TextLink, { href: resolvedStoreHref, variant: "none", className: activeDashboardLink?.href === resolvedStoreHref ? navItemActiveClass : navItemClass, "aria-current": activeDashboardLink?.href === resolvedStoreHref ? "page" : undefined, children: labels.storeDashboard }) }))] }) })), normalizedSections.map((section, sectionIndex) => (_jsx(CollapsibleSidebarSection, { section: section, navItemClass: navItemClass, navItemActiveClass: navItemActiveClass, activeHref: activeHref }, `sidebar-section-${sectionIndex}`))), (sidebarLocaleSlot || showThemeToggleInSidebar || (isAuthenticated && onLogout)) && (_jsxs(Stack, { border: "default", className: "border-t border-[var(--appkit-color-border-subtle)]", padding: "t-md", gap: "3", children: [sidebarLocaleSlot, showThemeToggleInSidebar && (_jsxs("button", { type: "button", onClick: toggleTheme, className: "flex w-full items-center justify-end gap-[var(--appkit-space-3)] rounded-lg px-[var(--appkit-space-3)] py-[var(--appkit-space-2)] text-[length:var(--appkit-text-sm)] text-[var(--appkit-color-text-muted)] transition-colors hover:bg-primary-surface hover:text-primary-800 dark:hover:text-primary-200", children: [_jsx(Span, { "aria-hidden": "true", children: theme === "dark" ? "☀️" : "🌙" }), activeThemeName] })), isAuthenticated && onLogout && (_jsx("button", { type: "button", onClick: () => { onLogout(); onAfterLogout(); }, className: CLS_LOGOUT_BTN, children: labels.logout }))] }))] }));
 }
 // ─── Main component ────────────────────────────────────────────────────────────
 export function AppLayoutShell({ children, navItems, sidebarItems = [], sidebarSections, sidebarPrimaryActions, sidebarTitle = "Navigation", hiddenNavItems, user, brandName, brandShortName, siteLogoUrl, logoHref, promotionsHref, cartHref, wishlistHref, messagesHref, unreadMessageCount, userId, profileHref, loginHref, registerHref, homeHref, shopHref, footer, searchSlot, searchSlotRenderer, titleBarNavSlot, titleBarNotificationSlot, titleBarDevSlot, titleBarPromoStripText, showThemeToggle = false, suppressDashboardNav = false, hideSidebarToggle = false, onLogout, adminHref, storeHref, sellerHref, userOrdersHref, userWishlistHref, userSettingsHref, sidebarLocaleSlot, showThemeToggleInSidebar = false, sidebarProfileLabels, eventBannerSlot, showBottomNav = true, contentClassName, lightBackground = DEFAULT_LIGHT_BG, darkBackground = DEFAULT_DARK_BG, }) {