@mohasinac/appkit 4.55.0 → 4.57.0

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

@@ -1,13 +1,13 @@
 "use client";
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { THEMED_TEXT_SECONDARY, FLEX_CENTER } from "../../../_internal/shared/styles/themed.js";
-import { Button, Div, Grid, Heading, Icon, ImageMosaic, MOSAIC_MIN, Row, Section, SiteLogo, SiteMark, Span, Stack, Text, TextLink } from "../../../ui/index.js";
+import { Button, Div, Grid, Heading, Icon, ImageMosaic, Row, Section, SiteLogo, SiteMark, Span, Stack, Text, TextLink } from "../../../ui/index.js";
 // --- Component ---------------------------------------------------------------
-export function WelcomeSection({ title, subtitle, pillLabel, showCTA = true, ctaLabel = "Shop now", ctaHref, onCtaClick, secondaryCtaLabel = "Browse products", secondaryCtaHref, onSecondaryCtaClick, trustChips = [], heroImages, isLoading = false, brandLogoText = "", className = "", }) {
+export function WelcomeSection({ title, subtitle, pillLabel, showCTA = true, ctaLabel = "Shop now", ctaHref, onCtaClick, secondaryCtaLabel = "Browse products", secondaryCtaHref, onSecondaryCtaClick, trustChips = [], heroImages, isLoading = false, brandLogoText = "", brandCaption, className = "", }) {
     const themed = { textSecondary: THEMED_TEXT_SECONDARY };
     const flex = { center: FLEX_CENTER };
     if (isLoading) {
         return (_jsx(Section, { className: `relative overflow-hidden pt-[0px] pb-[var(--appkit-space-16)] md:pt-[0px] md:pb-[6rem] ${className}`, paddingX: "x-md", children: _jsxs(Div, { className: "animate-pulse max-w-4xl mx-auto text-left", children: [_jsx(Div, { className: "h-6 w-52 mb-6", surface: "subtle", rounded: "full" }), _jsx(Div, { className: "h-20 mb-4 max-w-2xl", surface: "subtle", rounded: "lg" }), _jsx(Div, { className: "h-6 mb-8 max-w-lg", surface: "subtle", rounded: "lg" }), _jsxs(Row, { justify: "start", gap: "md", children: [_jsx(Div, { className: "h-12 w-36", surface: "subtle", rounded: "xl" }), _jsx(Div, { className: "h-12 w-36", surface: "subtle", rounded: "xl" })] })] }) }));
     }
-    return (_jsxs(Section, { className: `relative overflow-hidden pt-[0px] pb-[var(--appkit-space-20)] md:pt-[0px] md:pb-[7rem] ${className}`, paddingX: "x-md", children: [_jsx(Div, { className: "pointer-events-none absolute -top-32 -left-32 w-[28rem] h-[28rem] bg-primary/10 blur-3xl", rounded: "full", "aria-hidden": "true" }), _jsx(Div, { className: "pointer-events-none absolute -bottom-40 -right-40 w-[36rem] h-[36rem] bg-secondary/10 dark:bg-secondary/15 blur-3xl", rounded: "full", "aria-hidden": "true" }), _jsx(Div, { className: "relative z-10 max-w-7xl mx-auto", children: _jsxs(Grid, { align: "center", gap: "2xl", className: "grid-cols-1 lg:grid-cols-2 xl:grid-cols-2 2xl:grid-cols-2", children: [_jsxs(Div, { className: "text-left", children: [pillLabel && (_jsx(Div, { children: _jsxs(Span, { layout: "inline-flex", gap: "md", size: "xs", weight: "medium", className: /* audit-variant-ok: colour+alpha border (primary-500/30); the `border` variant takes a token name, not an rgba step */ "border border-primary-500/30 bg-primary-500/10 px-[1.25rem] py-[0.375rem] tracking-[0.2em] text-primary-700 dark:text-primary-400 backdrop-blur-sm", rounded: "full", transform: "uppercase", children: [_jsx(Span, { className: "w-1.5 h-1.5 bg-primary-500 inline-block", rounded: "full", "aria-hidden": "true" }), pillLabel, _jsx(Span, { className: "w-1.5 h-1.5 bg-primary-500 inline-block", rounded: "full", "aria-hidden": "true" })] }) })), _jsx(Heading, { level: 1, variant: "none", gradient: "brand-tri", className: "mt-4 font-display leading-[1.1] tracking-tight break-words", size: "5xl", mdSize: "6xl", lgSize: "7xl", xlSize: "7xl", children: title }), subtitle && (_jsx(Text, { className: `mt-4 ${themed.textSecondary} max-w-xl leading-relaxed`, size: "xl", children: subtitle })), showCTA && (_jsxs(Row, { wrap: true, gap: "md", className: "mt-8", justify: "start", children: [ctaHref ? (_jsx(TextLink, { rounded: "xl", href: ctaHref, layout: "inline-flex", align: "center", justify: "center", className: "px-[2rem] py-[0.875rem] !bg-primary hover:!bg-primary-600 text-white dark:!bg-primary dark:hover:!bg-primary-600 dark:text-white btn-glow transition-all hover:scale-[1.02]", size: "base", weight: "bold", children: ctaLabel })) : (_jsx(Button, { variant: "primary", size: "lg", onClick: onCtaClick, children: ctaLabel })), secondaryCtaHref ? (_jsx(TextLink, { rounded: "xl", href: secondaryCtaHref, layout: "inline-flex", align: "center", justify: "center", className: "border-2 border-cobalt/40 dark:border-cobalt-400/40 px-[2rem] py-[0.875rem] text-cobalt-700 dark:text-cobalt-300 hover:bg-primary-surface transition-all hover:scale-[1.02]", size: "base", weight: "semibold", children: secondaryCtaLabel })) : (_jsx(Button, { variant: "outline", size: "lg", onClick: onSecondaryCtaClick, children: secondaryCtaLabel }))] })), trustChips.length > 0 && (_jsx(Row, { wrap: true, gap: "sm", className: "mt-6", justify: "start", children: trustChips.map((chip) => (_jsxs(Row, { align: "center", gap: "xs", surface: "default", border: "subtle", rounded: "full", shadow: "sm", className: "px-[0.875rem] py-[0.375rem]", children: [_jsx(Icon, { name: chip.iconName, size: "sm", tone: "success" }), _jsx(Span, { size: "xs", weight: "medium", color: "muted", children: chip.label })] }, chip.key))) }))] }), _jsx(Div, { className: "hidden lg:block", children: heroImages && heroImages.length >= MOSAIC_MIN ? (_jsx(ImageMosaic, { size: "hero", images: heroImages, alt: `${brandLogoText || "Marketplace"} collection highlights` })) : (_jsxs(Div, { className: `relative overflow-hidden aspect-[4/3] bg-[image:var(--appkit-gradient-section-mesh)]`, shadow: "2xl", border: "default", rounded: "3xl", children: [_jsx(Div, { className: "absolute inset-0 bg-[image:var(--appkit-gradient-glass)]" }), _jsxs(Stack, { centered: true, gap: "sm", className: `absolute inset-0 ${flex.center} p-[2.5rem]`, children: [_jsx(SiteMark, { title: brandLogoText || "LetItRip.in", size: "xl" }), _jsx(SiteLogo, { title: brandLogoText || "LetItRip.in", size: "xl" })] })] })) })] }) })] }));
+    return (_jsxs(Section, { className: `relative overflow-hidden pt-[0px] pb-[var(--appkit-space-20)] md:pt-[0px] md:pb-[7rem] ${className}`, paddingX: "x-md", children: [_jsx(Div, { className: "pointer-events-none absolute -top-32 -left-32 w-[28rem] h-[28rem] bg-primary/10 blur-3xl", rounded: "full", "aria-hidden": "true" }), _jsx(Div, { className: "pointer-events-none absolute -bottom-40 -right-40 w-[36rem] h-[36rem] bg-secondary/10 dark:bg-secondary/15 blur-3xl", rounded: "full", "aria-hidden": "true" }), _jsx(Div, { className: "relative z-10 max-w-7xl mx-auto", children: _jsxs(Grid, { align: "center", gap: "2xl", className: "grid-cols-1 lg:grid-cols-2 xl:grid-cols-2 2xl:grid-cols-2", children: [_jsxs(Div, { className: "text-left", children: [pillLabel && (_jsx(Div, { children: _jsxs(Span, { layout: "inline-flex", gap: "md", size: "xs", weight: "medium", className: /* audit-variant-ok: colour+alpha border (primary-500/30); the `border` variant takes a token name, not an rgba step */ "border border-primary-500/30 bg-primary-500/10 px-[1.25rem] py-[0.375rem] tracking-[0.2em] text-primary-700 dark:text-primary-400 backdrop-blur-sm", rounded: "full", transform: "uppercase", children: [_jsx(Span, { className: "w-1.5 h-1.5 bg-primary-500 inline-block", rounded: "full", "aria-hidden": "true" }), pillLabel, _jsx(Span, { className: "w-1.5 h-1.5 bg-primary-500 inline-block", rounded: "full", "aria-hidden": "true" })] }) })), _jsx(Heading, { level: 1, variant: "none", gradient: "brand-tri", className: "mt-4 font-display leading-[1.1] tracking-tight break-words", size: "5xl", mdSize: "6xl", lgSize: "7xl", xlSize: "7xl", children: title }), subtitle && (_jsx(Text, { className: `mt-4 ${themed.textSecondary} max-w-xl leading-relaxed`, size: "xl", children: subtitle })), showCTA && (_jsxs(Row, { wrap: true, gap: "md", className: "mt-8", justify: "start", children: [ctaHref ? (_jsx(TextLink, { rounded: "xl", href: ctaHref, layout: "inline-flex", align: "center", justify: "center", className: "px-[2rem] py-[0.875rem] !bg-primary hover:!bg-primary-600 text-white dark:!bg-primary dark:hover:!bg-primary-600 dark:text-white btn-glow transition-all hover:scale-[1.02]", size: "base", weight: "bold", children: ctaLabel })) : (_jsx(Button, { variant: "primary", size: "lg", onClick: onCtaClick, children: ctaLabel })), secondaryCtaHref ? (_jsx(TextLink, { rounded: "xl", href: secondaryCtaHref, layout: "inline-flex", align: "center", justify: "center", className: "border-2 border-cobalt/40 dark:border-cobalt-400/40 px-[2rem] py-[0.875rem] text-cobalt-700 dark:text-cobalt-300 hover:bg-primary-surface transition-all hover:scale-[1.02]", size: "base", weight: "semibold", children: secondaryCtaLabel })) : (_jsx(Button, { variant: "outline", size: "lg", onClick: onSecondaryCtaClick, children: secondaryCtaLabel }))] })), trustChips.length > 0 && (_jsx(Row, { wrap: true, gap: "sm", className: "mt-6", justify: "start", children: trustChips.map((chip) => (_jsxs(Row, { align: "center", gap: "xs", surface: "default", border: "subtle", rounded: "full", shadow: "sm", className: "px-[0.875rem] py-[0.375rem]", children: [_jsx(Icon, { name: chip.iconName, size: "sm", tone: "success" }), _jsx(Span, { size: "xs", weight: "medium", color: "muted", children: chip.label })] }, chip.key))) }))] }), _jsx(Div, { className: "hidden lg:block", children: _jsx(ImageMosaic, { size: "hero", images: heroImages ?? [], alt: `${brandLogoText || "Marketplace"} collection highlights`, leadSlot: _jsxs(Div, { className: "absolute inset-0 bg-[image:var(--appkit-gradient-section-mesh)]", children: [_jsx(Div, { className: "absolute inset-0 bg-[image:var(--appkit-gradient-glass)]" }), _jsxs(Stack, { centered: true, gap: "sm", padding: "xl", className: `absolute inset-0 ${flex.center}`, children: [_jsx(SiteMark, { title: brandLogoText || "LetItRip.in", size: "xl" }), _jsx(SiteLogo, { title: brandLogoText || "LetItRip.in", size: "xl" }), brandCaption && (_jsx(Text, { align: "center", size: "sm", weight: "semibold", transform: "uppercase", className: "tracking-widest text-primary-700 dark:text-primary-300", children: brandCaption }))] })] }) }) })] }) })] }));
 }

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

@@ -46,6 +46,15 @@ export interface HomepageBrand {
     name?: string;
     /** Short mark shown in the hero panel, e.g. "LT". */
     shortName?: string;
+    /**
+     * Caption under the hero brand panel's logo, e.g. "Let It Rip India".
+     *
+     * Separate from `name` because that one is a sentence ingredient ("Why
+     * Buyers Trust LetItRip") and this one is a standalone lockup line — they
+     * are spelled differently on purpose and collapsing them would force one of
+     * the two to read wrong.
+     */
+    heroCaption?: string;
 }
 /**
  * Every surface a `SectionDef` may be mounted on.

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

@@ -1,6 +1,11 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import React from "react";
 import { ROUTES } from "../../../next/routing/route-map.js";
+/* Defining module, not the `ui`/root barrel — Root Cause #18. This is the one
+   owner of "what a generated placeholder tile looks like"; the seed helper's
+   `isSeedPlaceholderImage` reads the same prefix from its own copy, and both
+   are documented as mirrors of `public/images/seed-tiles/`. */
+import { SEED_TILE_PREFIX } from "../../../utils/media-url.js";
 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";
@@ -43,6 +48,7 @@ import { CollectionCardsSection } from "../components/CollectionCardsSection.js"
 import { HowItWorksSection } from "../components/HowItWorksSection.js";
 import { TestimonialsCarousel } from "../components/TestimonialsCarousel.js";
 import { PromoGrid } from "../components/PromoGrid.js";
+import { OwnerQuickActions } from "../../admin/components/OwnerQuickActions.js";
 const AD_SLOT_MAP = {
     carousel: "afterHero",
     products: "afterFeaturedProducts",
@@ -76,21 +82,33 @@ const SECTION_REGISTRY = {
             /*
              * Hero imagery, taken from the featured categories' own covers.
              *
-             * Deterministic — the first five in CONFIGURED order, never shuffled, so
+             * Deterministic — the first few 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).
              *
+             * 🛑 PLACEHOLDERS ARE DROPPED, and on this install that is most of them.
+             * `seedPhoto()` returns one of six flat SVG tiles under
+             * `SEED_TILE_PREFIX` whenever the seed has no real artwork, and
+             * `listTopLevelCategories` returns exactly the rows that have none —
+             * measured against production, 4 of the first 12 covers were tiles and
+             * the hero's large cell was `/images/seed-tiles/312e81.svg`. Those are
+             * not photographs of anything; passing them through meant the hero
+             * advertised the catalogue with coloured rectangles.
+             *
+             * Four, not five: the brand panel now owns the large cell, so the mosaic
+             * has one fewer slot to fill (see `ImageMosaic.leadSlot`).
+             *
              * 🛑 `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.
+             * collapses to the brand panel alone 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, 
+                .filter((src) => Boolean(src) && !src.startsWith(SEED_TILE_PREFIX))
+                .slice(0, 4);
+            return (_jsx(WelcomeSection, { heroImages: heroImages, brandCaption: brand?.heroCaption, 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 }));
@@ -416,6 +434,6 @@ export function renderSection(section, adSlots, newsletterFormSlot, faqItems, sl
     if (!sectionElement)
         return null;
     const adSlotKey = AD_SLOT_MAP[section.type];
-    return (_jsxs(React.Fragment, { children: [_jsx(HomepageSectionBoundary, { sectionId: section.id, sectionType: section.type, children: sectionElement }), adSlots && adSlotKey !== undefined && adSlotKey in adSlots && adSlots[adSlotKey]] }, section.id));
+    return (_jsxs(React.Fragment, { children: [_jsx(OwnerQuickActions, { resource: "SECTION", placement: "detail", className: "justify-end", recordLabel: section.type, editHref: String(ROUTES.ADMIN.SECTIONS) }), _jsx(HomepageSectionBoundary, { sectionId: section.id, sectionType: section.type, children: sectionElement }), adSlots && adSlotKey !== undefined && adSlotKey in adSlots && adSlots[adSlotKey]] }, section.id));
 }
 export { AnnouncementBar, hashBannerMessage };

package/dist/features/homepage/lib/slide-gating.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Carousel gating — strip slides and cards that advertise a disabled listing
+ * type.
+ *
+ * ## The gap this closes
+ *
+ * `MarketplaceHomepageView` already drops whole SECTIONS whose type maps to a
+ * disabled listing type (`HOMEPAGE_SECTION_LISTING_TYPE`). That gate is keyed
+ * on `SectionType`, so it can only see sections that ARE a listing type — the
+ * auctions rail, the pre-orders rail.
+ *
+ * A carousel is one section of type `carousel` whatever it contains, and what
+ * it contains is free-text authored content. With `auction: false` live, the
+ * hero still shipped a "Live auctions — place a bid before the timer runs out"
+ * card and a full-screen "Win it at your price" slide, both linking to
+ * `/auctions`, which renders nothing. The section gate could not see either:
+ * the only thing identifying them is where they point.
+ *
+ * ## Deliberately link-based, not keyword-based
+ *
+ * Nothing here reads the copy. "Win it at your price" names no type, and a
+ * word search would be both incomplete (it misses that slide) and
+ * over-eager (it would eat the authenticity slide for saying "bid" in passing).
+ * A destination is checkable; prose is not.
+ *
+ * ## What survives
+ *
+ * A slide keeps its authored `zone` values when a card is removed. Re-packing
+ * the survivors is NOT done here: the zone grid is a fixed `repeat(3, 1fr)`,
+ * so there is no arrangement of two cards that fills it, and silently moving
+ * an admin's card is a worse surprise than the gap. The seeded hero therefore
+ * replaces its auction card with a real enabled type rather than relying on
+ * this filter to tidy up after it — this is the safety net for content an
+ * admin authors later, where the gap is a visible prompt to go and fix it.
+ */
+import type { CarouselSlide } from "../types/index";
+import type { ListingType } from "../../products/types/index";
+interface ListingFlagSnapshot {
+    listings?: {
+        listingTypes?: Partial<Record<ListingType, boolean>>;
+    };
+}
+/**
+ * Filter a slide list for the current listing-type flags.
+ *
+ * Returns a new array; input is not mutated. Fails OPEN — with no settings
+ * document every `isListingTypeEnabled` call returns `true` and nothing is
+ * removed, which is the right failure for a read that errored (Root Cause
+ * #72: an unknown must never be read as "zero").
+ */
+export declare function gateCarouselSlides<T extends CarouselSlide>(slides: readonly T[], settings: ListingFlagSnapshot | null | undefined): T[];
+export {};

package/dist/features/homepage/lib/slide-gating.js

@@ -0,0 +1,98 @@
+/**
+ * Carousel gating — strip slides and cards that advertise a disabled listing
+ * type.
+ *
+ * ## The gap this closes
+ *
+ * `MarketplaceHomepageView` already drops whole SECTIONS whose type maps to a
+ * disabled listing type (`HOMEPAGE_SECTION_LISTING_TYPE`). That gate is keyed
+ * on `SectionType`, so it can only see sections that ARE a listing type — the
+ * auctions rail, the pre-orders rail.
+ *
+ * A carousel is one section of type `carousel` whatever it contains, and what
+ * it contains is free-text authored content. With `auction: false` live, the
+ * hero still shipped a "Live auctions — place a bid before the timer runs out"
+ * card and a full-screen "Win it at your price" slide, both linking to
+ * `/auctions`, which renders nothing. The section gate could not see either:
+ * the only thing identifying them is where they point.
+ *
+ * ## Deliberately link-based, not keyword-based
+ *
+ * Nothing here reads the copy. "Win it at your price" names no type, and a
+ * word search would be both incomplete (it misses that slide) and
+ * over-eager (it would eat the authenticity slide for saying "bid" in passing).
+ * A destination is checkable; prose is not.
+ *
+ * ## What survives
+ *
+ * A slide keeps its authored `zone` values when a card is removed. Re-packing
+ * the survivors is NOT done here: the zone grid is a fixed `repeat(3, 1fr)`,
+ * so there is no arrangement of two cards that fills it, and silently moving
+ * an admin's card is a worse surprise than the gap. The seeded hero therefore
+ * replaces its auction card with a real enabled type rather than relying on
+ * this filter to tidy up after it — this is the safety net for content an
+ * admin authors later, where the gap is a visible prompt to go and fix it.
+ */
+import { isDisabledListingHref } from "../../../_internal/shared/listing-types/route-gating.js";
+/**
+ * Every destination a card offers. A card with no buttons is still clickable
+ * through nothing — it has no link of its own — so it is never gated.
+ */
+function cardHrefs(card) {
+    return (card.buttons ?? []).map((b) => b.href).filter(Boolean);
+}
+/**
+ * A card is dropped when it HAS destinations and every one of them is
+ * disabled.
+ *
+ * 🛑 "every", not "any", and the empty case matters: `[].every()` is `true`,
+ * so a card with no buttons at all would be dropped by the predicate alone.
+ * That is why the length check is separate rather than folded in — an
+ * image-only card advertises no type and must survive.
+ */
+function isCardDisabled(card, settings) {
+    const hrefs = cardHrefs(card);
+    if (hrefs.length === 0)
+        return false;
+    return hrefs.every((href) => isDisabledListingHref(href, settings));
+}
+/**
+ * A slide is dropped when the thing it is ABOUT is disabled — its overlay CTA
+ * or its own whole-slide link.
+ *
+ * Both are checked because they are set independently: the seeded auction
+ * slide carries `overlay.button.link` AND `link.url`, while a slide can
+ * legitimately have only one.
+ */
+function isSlideDisabled(slide, settings) {
+    if (isDisabledListingHref(slide.overlay?.button?.link, settings))
+        return true;
+    if (isDisabledListingHref(slide.link?.url, settings))
+        return true;
+    return false;
+}
+/**
+ * Filter a slide list for the current listing-type flags.
+ *
+ * Returns a new array; input is not mutated. Fails OPEN — with no settings
+ * document every `isListingTypeEnabled` call returns `true` and nothing is
+ * removed, which is the right failure for a read that errored (Root Cause
+ * #72: an unknown must never be read as "zero").
+ */
+export function gateCarouselSlides(slides, settings) {
+    const kept = [];
+    for (const slide of slides) {
+        if (isSlideDisabled(slide, settings))
+            continue;
+        const cards = (slide.cards ?? []).filter((card) => !isCardDisabled(card, settings));
+        const hadCards = (slide.cards ?? []).length > 0;
+        // A cards-slide that lost ALL its cards renders as a bare background with
+        // no copy and no call to action — the exact "renders blank" failure the
+        // carousel seed file's own header warns about. Drop it rather than ship an
+        // empty frame the visitor can swipe to.
+        if (hadCards && cards.length === 0 && !slide.overlay)
+            continue;
+        kept.push(cards.length === (slide.cards ?? []).length ? slide : { ...slide, cards });
+    }
+    return kept;
+}

package/dist/features/live/components/LiveItemDetailPageView.js

@@ -26,6 +26,7 @@ import { getGroupsWithItemsForProduct } from "../../../_internal/server/features
 import { ReviewsListingPanel } from "../../reviews/components/ReviewsListingPanel.js";
 import { ListingBottomActions } from "../../products/components/ListingBottomActions.js";
 import { productImageUrls } from "../../products/schemas/firestore.js";
+import { PurchaseReviewAffordance } from "../../reviews/components/PurchaseReviewAffordance.js";
 function toDescriptionHtml(raw) {
     if (!raw)
         return "";
@@ -79,5 +80,5 @@ export async function LiveItemDetailPageView({ slug, initialProduct, renderActio
                     price: price ?? undefined,
                     storeId: typeof p.storeId === "string" ? p.storeId : undefined,
                     storeName: storeName ?? undefined,
-                } }), _jsxs(Container, { size: "xl", padding: "y-lg", children: [_jsxs(Row, { className: "mb-4", align: "center", justify: "between", gap: "sm", wrap: true, children: [_jsxs(Nav, { "aria-label": "Breadcrumb", layout: "flex-wrap", gap: "2xs", textSize: "xs", color: "muted", children: [_jsx(Link, { href: String(ROUTES.HOME), className: CLS_BREADCRUMB_LINK, children: "Home" }), _jsx(Span, { "aria-hidden": true, children: "/" }), _jsx(Link, { href: String(ROUTES.PUBLIC.LIVE), className: CLS_BREADCRUMB_LINK, children: "Live" }), category && (_jsxs(_Fragment, { children: [_jsx(Span, { "aria-hidden": true, children: "/" }), _jsx(Link, { href: String(ROUTES.PUBLIC.CATEGORY_DETAIL(category)), className: CLS_BREADCRUMB_LINK, children: categoryName || category })] })), _jsx(Span, { "aria-hidden": true, children: "/" }), _jsx(Span, { className: "truncate max-w-[200px]", color: "muted", children: title })] }), _jsx(ShareButton, { title: title })] }), _jsx(PreOrderDetailView, { renderGallery: () => _jsx(ProductGalleryClient, { images: images, video: productVideo, productName: title }), renderInfo: () => (_jsxs(Stack, { gap: "md", children: [_jsxs(Div, { children: [_jsxs(Row, { gap: "xs", wrap: true, className: "mb-2", children: [_jsx(Span, { size: "xs", weight: "semibold", className: CLS_LIVE_ITEM_BADGE, children: "Live Item" }), meta?.vendorVerified && (_jsx(Span, { color: "success", surface: "success-surface", size: "xs", weight: "medium", className: "inline-block", padding: "pill-sm", rounded: "full", children: "Verified Seller" })), meta?.cites && (_jsxs(Span, { color: "warning", surface: "warning-surface", size: "xs", weight: "medium", className: "inline-block", padding: "pill-sm", rounded: "full", children: ["CITES: ", meta.cites] }))] }), _jsx(OwnerQuickActions, { resource: "PRODUCT", placement: "detail", recordLabel: String(p.title ?? p.slug ?? p.id), storeId: p.storeId ? String(p.storeId) : undefined, editHref: String(ROUTES.STORE.PRODUCTS_EDIT(String(p.id))) }), _jsx(Heading, { level: 1, className: "leading-snug", smSize: "2xl", color: "primary", size: "xl", weight: "bold", children: title }), meta?.species && (_jsxs(Text, { className: "italic mt-1", color: "muted", size: "sm", children: [meta.species, meta.sex && meta.sex !== "n/a" && ` · ${meta.sex}`, meta.ageMonths !== undefined && ` · ${meta.ageMonths}mo`] }))] }), price !== null && (_jsx(Text, { size: "2xl", weight: "bold", color: "primary", children: _jsx(GatedPrice, { children: formatCurrency(price, currency) }) })), jurisdictions.length > 0 && (_jsxs(Div, { className: CLS_WARN_BOX, children: [_jsx(Text, { className: CLS_WARN_TITLE, children: "Delivery restrictions" }), _jsxs(Text, { className: CLS_WARN_BODY, children: ["This item can only be shipped to: ", jurisdictions.join(", ")] })] })), transport && (_jsxs(Div, { textSize: "sm", border: "subtle", surface: "muted", padding: "md", rounded: "lg", children: [_jsx(Text, { weight: "medium", children: "Transport" }), _jsxs(Text, { className: "text-[var(--appkit-color-text-muted)]", children: ["Method: ", transport.method, transport.handlingFee !== undefined && (_jsx(PricesOnly, { children: ` · Handling: ${formatCurrency(transport.handlingFee, "INR")}` })), transport.insuranceIncluded && " · Insurance included"] })] })), meta?.careInfo && (_jsxs(Div, { textSize: "sm", border: "subtle", surface: "muted", padding: "md", rounded: "lg", children: [_jsx(Text, { weight: "medium", children: "Care information" }), _jsx(Text, { className: "mt-1 text-[var(--appkit-color-text-muted)]", children: meta.careInfo })] })), descriptionHtml && (_jsx(RichText, { html: descriptionHtml, proseClass: "prose prose-sm max-w-none dark:prose-invert prose-p:my-0", className: "text-[length:var(--appkit-text-sm)] leading-relaxed text-[var(--appkit-color-text-muted)] line-clamp-4" })), safeSeller && (_jsx(Div, { border: "subtle", rounded: "xl", surface: "muted", padding: "md", children: _jsxs(Row, { justify: "between", align: "center", children: [_jsxs(Div, { children: [_jsx(Text, { className: "text-[10px] tracking-wide mb-0.5", color: "faint", transform: "uppercase", children: "Sold by" }), _jsx(Text, { size: "sm", weight: "semibold", color: "primary", children: safeSeller })] }), storeHref && (_jsx(Link, { href: storeHref, className: "shrink-0 rounded-lg bg-primary/10 dark:bg-primary/20 px-[var(--appkit-space-3)] py-[var(--appkit-space-1-5)] text-[length:var(--appkit-text-xs)] font-semibold text-primary-700 dark:text-primary-300 hover:bg-primary/20 dark:hover:bg-primary/30 transition-colors", children: "Visit Store \u2192" }))] }) }))] })), renderTabs: () => (_jsx(ProductTabsShell, { descriptionContent: descriptionHtml ? (_jsx(RichText, { html: descriptionHtml, proseClass: "prose prose-sm sm:prose max-w-none dark:prose-invert", className: "text-[var(--appkit-color-text-muted)]" })) : undefined, specsContent: specs.length > 0 ? (_jsx(SpecTable, { rows: specs })) : undefined, reviewsContent: _jsx(ReviewsListingPanel, { source: { kind: "product", productId: product.id }, stateMode: "local", context: "listing", initialData: initialReviews, emptyLabel: "No reviews yet \u2014 be the first to review this product." }), customTabs: toCustomSectionTabs(p.customSections) })), renderBuyBar: () => _jsx(Div, { id: "live-item-buy-bar", children: renderActions?.(product) }), renderRelated: () => (_jsxs(Stack, { gap: "xl", children: [_jsx(GroupedListingsCarousel, { groups: groups }), _jsx(RelatedItemsSection, { relatedItems: relatedItems, relatedByBrand: relatedByBrand, relatedByTags: relatedByTags, relatedByStore: relatedByStore, categoryLabel: categoryName || category || undefined, brandLabel: brand, storeLabel: storeName ?? undefined })] })) }), _jsx(ListingBottomActions, { listingType: "live", anchorId: "live-item-buy-bar", price: price, currency: currency })] })] }));
+                } }), _jsxs(Container, { size: "xl", padding: "y-lg", children: [_jsxs(Row, { className: "mb-4", align: "center", justify: "between", gap: "sm", wrap: true, children: [_jsxs(Nav, { "aria-label": "Breadcrumb", layout: "flex-wrap", gap: "2xs", textSize: "xs", color: "muted", children: [_jsx(Link, { href: String(ROUTES.HOME), className: CLS_BREADCRUMB_LINK, children: "Home" }), _jsx(Span, { "aria-hidden": true, children: "/" }), _jsx(Link, { href: String(ROUTES.PUBLIC.LIVE), className: CLS_BREADCRUMB_LINK, children: "Live" }), category && (_jsxs(_Fragment, { children: [_jsx(Span, { "aria-hidden": true, children: "/" }), _jsx(Link, { href: String(ROUTES.PUBLIC.CATEGORY_DETAIL(category)), className: CLS_BREADCRUMB_LINK, children: categoryName || category })] })), _jsx(Span, { "aria-hidden": true, children: "/" }), _jsx(Span, { className: "truncate max-w-[200px]", color: "muted", children: title })] }), _jsx(ShareButton, { title: title })] }), _jsx(PreOrderDetailView, { renderGallery: () => _jsx(ProductGalleryClient, { images: images, video: productVideo, productName: title }), renderInfo: () => (_jsxs(Stack, { gap: "md", children: [_jsxs(Div, { children: [_jsxs(Row, { gap: "xs", wrap: true, className: "mb-2", children: [_jsx(Span, { size: "xs", weight: "semibold", className: CLS_LIVE_ITEM_BADGE, children: "Live Item" }), meta?.vendorVerified && (_jsx(Span, { color: "success", surface: "success-surface", size: "xs", weight: "medium", className: "inline-block", padding: "pill-sm", rounded: "full", children: "Verified Seller" })), meta?.cites && (_jsxs(Span, { color: "warning", surface: "warning-surface", size: "xs", weight: "medium", className: "inline-block", padding: "pill-sm", rounded: "full", children: ["CITES: ", meta.cites] }))] }), _jsx(OwnerQuickActions, { resource: "PRODUCT", placement: "detail", recordLabel: String(p.title ?? p.slug ?? p.id), storeId: p.storeId ? String(p.storeId) : undefined, editHref: String(ROUTES.STORE.PRODUCTS_EDIT(String(p.id))) }), _jsx(Heading, { level: 1, className: "leading-snug", smSize: "2xl", color: "primary", size: "xl", weight: "bold", children: title }), meta?.species && (_jsxs(Text, { className: "italic mt-1", color: "muted", size: "sm", children: [meta.species, meta.sex && meta.sex !== "n/a" && ` · ${meta.sex}`, meta.ageMonths !== undefined && ` · ${meta.ageMonths}mo`] }))] }), price !== null && (_jsx(Text, { size: "2xl", weight: "bold", color: "primary", children: _jsx(GatedPrice, { children: formatCurrency(price, currency) }) })), jurisdictions.length > 0 && (_jsxs(Div, { className: CLS_WARN_BOX, children: [_jsx(Text, { className: CLS_WARN_TITLE, children: "Delivery restrictions" }), _jsxs(Text, { className: CLS_WARN_BODY, children: ["This item can only be shipped to: ", jurisdictions.join(", ")] })] })), transport && (_jsxs(Div, { textSize: "sm", border: "subtle", surface: "muted", padding: "md", rounded: "lg", children: [_jsx(Text, { weight: "medium", children: "Transport" }), _jsxs(Text, { className: "text-[var(--appkit-color-text-muted)]", children: ["Method: ", transport.method, transport.handlingFee !== undefined && (_jsx(PricesOnly, { children: ` · Handling: ${formatCurrency(transport.handlingFee, "INR")}` })), transport.insuranceIncluded && " · Insurance included"] })] })), meta?.careInfo && (_jsxs(Div, { textSize: "sm", border: "subtle", surface: "muted", padding: "md", rounded: "lg", children: [_jsx(Text, { weight: "medium", children: "Care information" }), _jsx(Text, { className: "mt-1 text-[var(--appkit-color-text-muted)]", children: meta.careInfo })] })), descriptionHtml && (_jsx(RichText, { html: descriptionHtml, proseClass: "prose prose-sm max-w-none dark:prose-invert prose-p:my-0", className: "text-[length:var(--appkit-text-sm)] leading-relaxed text-[var(--appkit-color-text-muted)] line-clamp-4" })), safeSeller && (_jsx(Div, { border: "subtle", rounded: "xl", surface: "muted", padding: "md", children: _jsxs(Row, { justify: "between", align: "center", children: [_jsxs(Div, { children: [_jsx(Text, { className: "text-[10px] tracking-wide mb-0.5", color: "faint", transform: "uppercase", children: "Sold by" }), _jsx(Text, { size: "sm", weight: "semibold", color: "primary", children: safeSeller })] }), storeHref && (_jsx(Link, { href: storeHref, className: "shrink-0 rounded-lg bg-primary/10 dark:bg-primary/20 px-[var(--appkit-space-3)] py-[var(--appkit-space-1-5)] text-[length:var(--appkit-text-xs)] font-semibold text-primary-700 dark:text-primary-300 hover:bg-primary/20 dark:hover:bg-primary/30 transition-colors", children: "Visit Store \u2192" }))] }) }))] })), renderTabs: () => (_jsx(ProductTabsShell, { descriptionContent: descriptionHtml ? (_jsx(RichText, { html: descriptionHtml, proseClass: "prose prose-sm sm:prose max-w-none dark:prose-invert", className: "text-[var(--appkit-color-text-muted)]" })) : undefined, specsContent: specs.length > 0 ? (_jsx(SpecTable, { rows: specs })) : undefined, reviewsContent: _jsx(ReviewsListingPanel, { source: { kind: "product", productId: product.id }, stateMode: "local", context: "listing", initialData: initialReviews, emptyLabel: "No reviews yet \u2014 be the first to review this product." }), customTabs: toCustomSectionTabs(p.customSections) })), renderBuyBar: () => _jsx(Div, { id: "live-item-buy-bar", children: renderActions?.(product) }), renderRelated: () => (_jsxs(Stack, { gap: "xl", children: [_jsx(PurchaseReviewAffordance, { productId: String(product.id), storeId: product.storeId ? String(product.storeId) : undefined }), _jsx(GroupedListingsCarousel, { groups: groups }), _jsx(RelatedItemsSection, { relatedItems: relatedItems, relatedByBrand: relatedByBrand, relatedByTags: relatedByTags, relatedByStore: relatedByStore, categoryLabel: categoryName || category || undefined, brandLabel: brand, storeLabel: storeName ?? undefined })] })) }), _jsx(ListingBottomActions, { listingType: "live", anchorId: "live-item-buy-bar", price: price, currency: currency })] })] }));
 }

package/dist/features/media/MediaAvatar.js

@@ -8,6 +8,6 @@ const sizeClasses = {
     xl: "w-20 h-20",
 };
 export function MediaAvatar({ src, alt, size = "md", className = "", }) {
-    return (_jsx(Div, { className: `relative ${sizeClasses[size]} overflow-hidden flex-shrink-0 ${className}`, rounded: "full", children: _jsx(MediaImage, { src: src, alt: alt, size: "avatar" }) }));
+    return (_jsx(Div, { className: `relative ${sizeClasses[size]} overflow-hidden flex-shrink-0 ${className}`, rounded: "full", children: _jsx(MediaImage, { src: src, alt: alt, size: "avatar", objectFit: "cover" }) }));
 }
 export default MediaAvatar;

package/dist/features/media/MediaImage.d.ts

@@ -24,7 +24,24 @@ export interface MediaImageProps {
      * one slide the visitor can actually see.
      */
     fetchPriority?: "high" | "low" | "auto";
-    /** CSS object-fit applied to the underlying img element. Defaults to `'cover'`. */
+    /**
+     * CSS object-fit applied to the underlying img element. Defaults to
+     * `'contain'`.
+     *
+     * 🛑 THE DEFAULT CHANGED on 2026-10-20, from `'cover'`. `cover` fills the
+     * box by cropping whatever does not fit, which is right for a photograph
+     * that continues past its frame and wrong for this catalogue: most of its
+     * imagery is a product shot centred on white, where the crop takes the
+     * product and leaves the background. `contain` fits the whole subject
+     * inside the shape and letterboxes the remainder against the tile's own
+     * surface colour.
+     *
+     * Pass `'cover'` explicitly where a FILLED box is the component's contract
+     * rather than a preference — a full-bleed backdrop with text over it, or a
+     * circular avatar. Three call sites do: `MediaAvatar`, and the slide and
+     * card backgrounds in `HeroCarousel`. A letterboxed backdrop there would put
+     * the dim overlay and the headline on bare surface.
+     */
     objectFit?: "cover" | "contain";
     /**
      * Emoji or text to show when `src` is undefined.

package/dist/features/media/MediaImage.js

@@ -67,7 +67,7 @@ function resolveSrcSet(input) {
         .filter(Boolean)
         .join(", ");
 }
-export function MediaImage({ src, alt, size = "card", priority = false, loading, fetchPriority, objectFit = "cover", fallback, className, rounded, shadow, style, sources, onError, }) {
+export function MediaImage({ src, alt, size = "card", priority = false, loading, fetchPriority, objectFit = "contain", fallback, className, rounded, shadow, style, sources, onError, }) {
     const [hasError, setHasError] = useState(false);
     const [isLoaded, setIsLoaded] = useState(false);
     const [retryCount, setRetryCount] = useState(0);

package/dist/features/orders/components/EmiInstallmentsPanel.d.ts

@@ -0,0 +1,19 @@
+import React from "react";
+import type { EmiInstallment } from "../schemas/firestore";
+export interface EmiInstallmentsPanelProps {
+    orderId: string;
+    installments: readonly EmiInstallment[];
+    /** Sum of unpaid instalments, as recorded on the order. */
+    remainingBalance?: number;
+    currency?: string;
+    /**
+     * Submits one instalment. Supplied by the consumer so this component does
+     * no fetching of its own — the same slot shape the rest of the orders
+     * feature uses.
+     */
+    onSubmit: (input: {
+        installmentIndex: number;
+        transactionId: string;
+    }) => Promise<void>;
+}
+export declare function EmiInstallmentsPanel({ orderId, installments, remainingBalance, currency, onSubmit, }: EmiInstallmentsPanelProps): React.JSX.Element;

package/dist/features/orders/components/EmiInstallmentsPanel.js

@@ -0,0 +1,57 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useState } from "react";
+import { Badge, Button, Div, Form, Row, Stack, Text, useToast } from "../../../ui/index.js";
+import { FieldInput } from "../../../ui/forms/index.js";
+import { formatCurrency } from "../../../utils/number.formatter.js";
+import { normalizeError } from "../../../errors/normalize.js";
+function stateOf(i) {
+    if (i.status === "paid")
+        return "paid";
+    // A reference the buyer submitted but nobody has confirmed. The status
+    // field cannot express this: an instalment is created "pending" and stays
+    // "pending" until it is paid, so the presence of a reference is the signal.
+    if (i.transactionId)
+        return "awaiting-review";
+    return "payable";
+}
+const STATE_LABEL = {
+    paid: "Paid",
+    "awaiting-review": "Awaiting confirmation",
+    payable: "Due",
+};
+export function EmiInstallmentsPanel({ orderId, installments, remainingBalance, currency = "INR", onSubmit, }) {
+    const { showToast } = useToast();
+    const [openIndex, setOpenIndex] = useState(null);
+    const [reference, setReference] = useState("");
+    const [isSubmitting, setIsSubmitting] = useState(false);
+    const money = (value) => formatCurrency(value, currency);
+    const ordered = [...installments].sort((a, b) => a.index - b.index);
+    const outstanding = ordered.filter((i) => i.status !== "paid").length;
+    const submit = async (index) => {
+        setIsSubmitting(true);
+        try {
+            await onSubmit({ installmentIndex: index, transactionId: reference.trim() });
+            showToast("Payment reference submitted — the seller will confirm it.", "success");
+            setOpenIndex(null);
+            setReference("");
+        }
+        catch (err) {
+            void normalizeError(err);
+            // The action's own message is surfaced by the caller's error mapping;
+            // this only has to stop the panel pretending the submission landed.
+            showToast("Couldn't submit that payment. Please try again.", "error");
+        }
+        finally {
+            setIsSubmitting(false);
+        }
+    };
+    return (_jsx(Div, { surface: "card", border: "default", rounded: "lg", padding: "md", children: _jsxs(Stack, { gap: "sm", children: [_jsxs(Row, { align: "center", justify: "between", gap: "sm", children: [_jsx(Text, { weight: "semibold", children: "Your EMI plan" }), remainingBalance !== undefined && remainingBalance > 0 && (_jsxs(Text, { size: "sm", color: "muted", children: [money(remainingBalance), " outstanding across ", outstanding, " instalment", outstanding === 1 ? "" : "s"] }))] }), _jsx(Text, { size: "xs", color: "muted", children: "You can pay any instalment whenever you like, including ahead of its due date \u2014 paying early settles the plan sooner and does not cost more." }), _jsx(Stack, { gap: "xs", children: ordered.map((inst) => {
+                        const state = stateOf(inst);
+                        const due = inst.dueDate ? new Date(inst.dueDate) : null;
+                        return (_jsxs(Div, { border: "default", rounded: "md", padding: "sm", children: [_jsxs(Row, { align: "center", justify: "between", gap: "sm", className: "min-w-0", children: [_jsxs(Stack, { gap: "xs", className: "min-w-0", children: [_jsxs(Text, { size: "sm", weight: "medium", children: ["Instalment ", inst.index, " \u00B7 ", money(inst.amount)] }), _jsx(Text, { size: "xs", color: "muted", children: due ? `Due ${due.toLocaleDateString()}` : "No due date recorded" })] }), _jsxs(Row, { align: "center", gap: "xs", className: "flex-shrink-0", children: [_jsx(Badge, { variant: state === "paid" ? "success" : state === "awaiting-review" ? "warning" : "default", children: STATE_LABEL[state] }), state === "payable" && (_jsx(Button, { type: "button", size: "sm", variant: "secondary", onClick: () => {
+                                                        setOpenIndex(openIndex === inst.index ? null : inst.index);
+                                                        setReference("");
+                                                    }, children: openIndex === inst.index ? "Cancel" : "Pay now" }))] })] }), openIndex === inst.index && (_jsx(Div, { className: "mt-3", children: _jsx(Form, { onSubmit: (e) => e.preventDefault(), children: () => (_jsxs(Stack, { gap: "sm", children: [_jsxs(Text, { size: "xs", color: "muted", children: ["Transfer ", money(inst.amount), " to the seller, then enter the UTR or reference number so they can confirm it."] }), _jsx(FieldInput, { name: `emi-reference-${orderId}-${inst.index}`, label: "UTR / reference number", required: true, value: reference, onChange: setReference }), _jsx(Button, { type: "submit", size: "sm", isLoading: isSubmitting, disabled: reference.trim().length === 0 || isSubmitting, onClick: () => { void submit(inst.index); }, children: "Submit payment reference" })] })) }) }))] }, inst.index));
+                    }) })] }) }));
+}

package/dist/features/orders/components/index.d.ts

@@ -14,3 +14,4 @@ export { RefundRequestView } from "./RefundRequestView";
 export type { RefundRequestViewProps } from "./RefundRequestView";
 export { YourPurchaseStrip } from "./YourPurchaseStrip";
 export type { YourPurchaseStripProps, PurchaseContext } from "./YourPurchaseStrip";
+export { EmiInstallmentsPanel, type EmiInstallmentsPanelProps, } from "./EmiInstallmentsPanel";

package/dist/features/orders/components/index.js

@@ -7,3 +7,4 @@ export { OrderStatusTimeline } from "./OrderStatusTimeline.js";
 export { RefundHistoryTable } from "./RefundHistoryTable.js";
 export { RefundRequestView } from "./RefundRequestView.js";
 export { YourPurchaseStrip } from "./YourPurchaseStrip.js";
+export { EmiInstallmentsPanel, } from "./EmiInstallmentsPanel.js";

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

@@ -8,6 +8,7 @@ import type { ListingType } from "../../products/types";
 import type { StatusChangeEntry } from "../../../_internal/shared/history/index";
 import type { ReturnReason } from "../../../_internal/shared/features/orders/return-reasons";
 import type { ReturnCustodyState } from "../../../_internal/shared/features/returns/custody";
+import type { ActualShipmentCost, SelectedShippingQuote, ShippingReconciliation } from "../../../_internal/shared/shipping/quote";
 import type { Encrypted, Plaintext } from "../../../security/encrypted";
 export interface OrderSourceStandard {
     path: "standard";
@@ -550,6 +551,43 @@ export interface OrderDocument extends BaseDocument {
     shippingMethod?: ShippingMethod;
     shippingCarrier?: string;
     trackingUrl?: string;
+    /**
+     * The courier the BUYER picked at checkout, and what they were charged for
+     * it, frozen at order creation.
+     *
+     * 🛑 Stored, never recomputed. Carrier rates move hourly, so re-quoting at
+     * reconciliation time would compare the seller's real spend against a price
+     * nobody was ever charged, and the buyer's refund would depend on when a job
+     * happened to run. Same reasoning as `sourceContext`.
+     *
+     * `chargedRate` is the ₹50-rounded figure and is the ONLY one that is
+     * billed; `rawRate` is kept for the audit trail and is never rendered.
+     * Absent on orders placed before the picker shipped, and on any order whose
+     * seller ships manually — so every reader must treat absence as "no quote
+     * was taken", never as zero.
+     */
+    selectedShippingQuote?: SelectedShippingQuote;
+    /**
+     * What the seller actually spent on postage, recorded at dispatch.
+     *
+     * Written by the seller's ship action. Its presence is what makes an order
+     * eligible for reconciliation; its absence means the parcel has not been
+     * dispatched or the seller has not told us what it cost.
+     */
+    actualShipmentCost?: ActualShipmentCost;
+    /**
+     * The outcome of comparing the two above — computed ONCE, when the seller
+     * dispatches, and then left alone.
+     *
+     * 🛑 Its presence is the idempotency key for the points credit. Crediting is
+     * an append to a ledger, so a job that ran twice would pay the buyer twice
+     * and nothing downstream could tell the difference between that and two
+     * genuine savings. Every writer must check this field is unset before
+     * writing a `shipping_saving` entry.
+     */
+    shippingReconciliation?: ShippingReconciliation & {
+        reconciledAt: Date;
+    };
     /**
      * The carrier's label PDF, once a shipment has been booked.
      *

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

@@ -614,6 +614,7 @@ export declare const orderFirestoreSchema: z.ZodObject<{
     } | undefined;
     offerId?: string | undefined;
     orderType?: string | undefined;
+    isNonRefundable?: boolean | undefined;
     imageUrls?: string[] | undefined;
     refundFeeDeducted?: number | undefined;
     refundNetAmount?: number | undefined;
@@ -650,7 +651,6 @@ export declare const orderFirestoreSchema: z.ZodObject<{
     }[] | undefined;
     emiRemainingBalance?: number | undefined;
     emiComplete?: boolean | undefined;
-    isNonRefundable?: boolean | undefined;
     paymentBatchId?: string | undefined;
     refunds?: {
         type: "full" | "partial";
@@ -762,6 +762,7 @@ export declare const orderFirestoreSchema: z.ZodObject<{
     } | undefined;
     offerId?: string | undefined;
     orderType?: string | undefined;
+    isNonRefundable?: boolean | undefined;
     imageUrls?: string[] | undefined;
     refundFeeDeducted?: number | undefined;
     refundNetAmount?: number | undefined;
@@ -798,7 +799,6 @@ export declare const orderFirestoreSchema: z.ZodObject<{
     }[] | undefined;
     emiRemainingBalance?: number | undefined;
     emiComplete?: boolean | undefined;
-    isNonRefundable?: boolean | undefined;
     paymentBatchId?: string | undefined;
     refunds?: {
         type: "full" | "partial";

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

@@ -1,3 +1,4 @@
+import type { EmiInstallment } from "../schemas/firestore";
 import type { ListingType } from "../../products/types/index";
 import type { OrderType } from "../utils/order-splitter";
 import type { AppliedOrderDiscount, OrderSourceContext } from "../schemas/firestore";
@@ -183,6 +184,20 @@ export interface Order {
      * read it from site settings, because `gst` is in `PRIVATE_SITE_FIELDS`
      * after an earlier deny-list projection shipped it publicly (Root Cause #70).
      */
+    /**
+     * ── EMI, buyer-facing ─────────────────────────────────────────────────
+     *
+     * 🛑 Declared here because `EmiInstallmentsPanel` is useless without it,
+     * and the absence was Root Cause #57's exact shape: the whole EMI schedule
+     * sat on `OrderDocument` and `orderDocumentToOrder` mapped none of it, so
+     * every buyer surface would have rendered its "no EMI plan" fallback with
+     * a real plan on the record. That reads as "this order isn't on EMI"
+     * rather than as a bug, which is why it survives.
+     */
+    emiEnabled?: boolean;
+    emiInstallments?: EmiInstallment[];
+    /** Sum of unpaid instalments. 0 once the plan is settled. */
+    emiRemainingBalance?: number;
     supplierGstin?: string;
     supplierLegalName?: string;
     supplierAddress?: string;