@mohasinac/appkit 4.62.1 → 4.63.1

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

@@ -126,12 +126,27 @@ export interface UserDocument extends BaseDocument {
         isVacationMode?: boolean;
         vacationMessage?: string;
     };
+    /**
+     * 🛑 LEGACY AND UNMAINTAINED — do not read these to answer "how many X does
+     * this account have". Nothing in either repo writes them: every occurrence
+     * across the codebase is a read, and the only `stats.itemsSold` write is
+     * `StoreRepository`'s, on the STORE document. The values present in Firestore
+     * today are seed literals.
+     *
+     * `getBuyerActivityStats` / `getProfileStats` count the real collections, and
+     * every surface that showed a number now goes through them.
+     *
+     * Kept on the schema because the documents still carry the field and a
+     * migration to strip it would buy nothing. `rating` was REMOVED outright: it
+     * had no writer AND no buyer-rating concept behind it, so its one reader
+     * (`/admin/users/[id]`) rendered a tile guarded on a value that could never
+     * be set.
+     */
     stats?: {
         totalOrders: number;
         auctionsWon: number;
         itemsSold: number;
         reviewsCount: number;
-        rating?: number;
     };
     metadata?: {
         lastSignInTime?: Date;
@@ -334,7 +349,6 @@ export declare const USER_FIELDS: {
         readonly AUCTIONS_WON: "stats.auctionsWon";
         readonly ITEMS_SOLD: "stats.itemsSold";
         readonly REVIEWS_COUNT: "stats.reviewsCount";
-        readonly RATING: "stats.rating";
     };
     readonly METADATA: "metadata";
     readonly META: {

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

@@ -150,7 +150,8 @@ export const USER_FIELDS = {
         AUCTIONS_WON: "stats.auctionsWon",
         ITEMS_SOLD: "stats.itemsSold",
         REVIEWS_COUNT: "stats.reviewsCount",
-        RATING: "stats.rating",
+        // `RATING` removed — `stats.rating` had no writer and no buyer-rating
+        // concept behind it anywhere in the codebase.
     },
     METADATA: "metadata",
     META: {

package/dist/features/blog/actions/blog-actions.d.ts

@@ -9,6 +9,7 @@ export declare const createBlogPostSchema: z.ZodObject<{
     category: z.ZodEnum<["news", "tips", "guides", "updates", "community"]>;
     tags: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
     isFeatured: z.ZodDefault<z.ZodBoolean>;
+    isPinned: z.ZodDefault<z.ZodBoolean>;
     status: z.ZodDefault<z.ZodEnum<["draft", "published", "archived"]>>;
     coverImage: z.ZodOptional<z.ZodNullable<z.ZodUnion<[z.ZodObject<{
         url: z.ZodEffects<z.ZodString, string, string>;
@@ -78,6 +79,7 @@ export declare const createBlogPostSchema: z.ZodObject<{
     isFeatured: boolean;
     excerpt: string;
     readTimeMinutes: number;
+    isPinned: boolean;
     additionalImages: {
         type: "video" | "image" | "file";
         url: string;
@@ -124,6 +126,7 @@ export declare const createBlogPostSchema: z.ZodObject<{
     authorId?: string | undefined;
     authorName?: string | undefined;
     readTimeMinutes?: number | undefined;
+    isPinned?: boolean | undefined;
     additionalImages?: {
         type: "video" | "image" | "file";
         url: string;
@@ -148,6 +151,7 @@ export declare const updateBlogPostSchema: z.ZodObject<{
     category: z.ZodOptional<z.ZodEnum<["news", "tips", "guides", "updates", "community"]>>;
     tags: z.ZodOptional<z.ZodDefault<z.ZodArray<z.ZodString, "many">>>;
     isFeatured: z.ZodOptional<z.ZodDefault<z.ZodBoolean>>;
+    isPinned: z.ZodOptional<z.ZodDefault<z.ZodBoolean>>;
     status: z.ZodOptional<z.ZodDefault<z.ZodEnum<["draft", "published", "archived"]>>>;
     coverImage: z.ZodOptional<z.ZodOptional<z.ZodNullable<z.ZodUnion<[z.ZodObject<{
         url: z.ZodEffects<z.ZodString, string, string>;
@@ -229,6 +233,7 @@ export declare const updateBlogPostSchema: z.ZodObject<{
     authorId?: string | undefined;
     authorName?: string | undefined;
     readTimeMinutes?: number | undefined;
+    isPinned?: boolean | undefined;
     additionalImages?: {
         type: "video" | "image" | "file";
         url: string;
@@ -263,6 +268,7 @@ export declare const updateBlogPostSchema: z.ZodObject<{
     authorId?: string | undefined;
     authorName?: string | undefined;
     readTimeMinutes?: number | undefined;
+    isPinned?: boolean | undefined;
     additionalImages?: {
         type: "video" | "image" | "file";
         url: string;

package/dist/features/blog/actions/blog-actions.js

@@ -6,6 +6,8 @@ import { blogRepository } from "../repository/blog.repository.js";
 import { coerceMediaField, getMediaUrl } from "../../../utils/index.js";
 import { hidePublicTestData } from "../../../_internal/server/features/tester/visibility.js";
 import { finalizeStagedMediaField, finalizeStagedMediaObject, finalizeStagedMediaObjectArray, } from "../../media/finalize.js";
+// Defining module, not the `../schemas` barrel — Root Cause #18.
+import { BLOG_DEFAULT_PUBLIC_SORT } from "../schemas/firestore.js";
 // --- Schemas --------------------------------------------------------------
 const singleImageMediaSchema = z
     .union([
@@ -33,6 +35,11 @@ export const createBlogPostSchema = z.object({
     category: z.enum(["news", "tips", "guides", "updates", "community"]),
     tags: z.array(z.string()).default([]),
     isFeatured: z.boolean().default(false),
+    // `.default(false)` is required, not cosmetic: `isPinned` is the first key of
+    // the public default sort, and Firestore excludes a document that lacks an
+    // `orderBy` field (Root Cause #100). A create that omitted it would write a
+    // post that cannot appear on its own index.
+    isPinned: z.boolean().default(false),
     status: z.enum(["draft", "published", "archived"]).default("draft"),
     coverImage: singleImageMediaSchema,
     contentImages: z.array(mediaFieldSchema).max(10).optional().default([]),
@@ -108,8 +115,16 @@ export async function getFeaturedBlogPosts(count = 3) {
     return hidePublicTestData(result.items);
 }
 export async function getLatestBlogPosts(count = 5) {
-    const result = await blogRepository.listPublished({}, { sorts: sortBy("publishedAt", "DESC"), page: 1, pageSize: count });
-    return result.items;
+    const result = await blogRepository.listPublished({}, { sorts: BLOG_DEFAULT_PUBLIC_SORT, page: 1, pageSize: count });
+    /*
+     * 🛑 `hidePublicTestData` was MISSING here while its sibling
+     * `getFeaturedBlogPosts` has always had it. This function feeds the homepage
+     * `blog-articles` section, so the seeded sandbox post was reaching the
+     * busiest public page on the site — the exact shape
+     * `audit-public-test-data-leak` exists to block, in the one blog path it
+     * does not scan.
+     */
+    return hidePublicTestData(result.items);
 }
 export async function getBlogPostById(id) {
     return blogRepository.findById(id);

package/dist/features/blog/api/route.js

@@ -9,6 +9,7 @@
  * ```
  */
 import { blogRepository } from "../repository/blog.repository.js";
+import { BLOG_DEFAULT_PUBLIC_SORT } from "../schemas/firestore.js";
 import { NextResponse } from "next/server.js";
 import { getProviders } from "../../../contracts/index.js";
 import { normalizeError } from "../../../errors/normalize.js";
@@ -34,7 +35,9 @@ export async function GET(request) {
         const pageSize = url.searchParams.has("perPage")
             ? numParam(url, "perPage", 20)
             : numParam(url, "pageSize", 20);
-        const sort = param(url, "sort") ?? "-publishedAt";
+        // Must be the SAME constant the SSR view uses — the view's result becomes
+        // this route's `initialData` under `staleTime: Infinity` (Root Cause #30).
+        const sort = param(url, "sort") ?? BLOG_DEFAULT_PUBLIC_SORT;
         const parts = [];
         const category = param(url, "category");
         if (category)

package/dist/features/blog/columns/index.js

@@ -25,6 +25,11 @@ export const blogAdminColumns = [
         header: "Featured",
         render: (p) => (p.isFeatured ? "Yes" : "No"),
     },
+    {
+        key: "isPinned",
+        header: "Pinned",
+        render: (p) => (p.isPinned ? "Yes" : "No"),
+    },
     {
         key: "readTimeMinutes",
         header: "Read Time",

package/dist/features/blog/components/BlogIndexPageView.js

@@ -3,6 +3,7 @@ import { blogRepository } from "../../../repositories/index.js";
 import { Container, Heading, Main, Section } from "../../../ui/index.js";
 import { AdSlot } from "../../homepage/components/AdSlot.js";
 import { BlogIndexListing } from "./BlogIndexListing.js";
+import { BLOG_DEFAULT_PUBLIC_SORT } from "../schemas/firestore.js";
 import { safeRead } from "../../../errors/safe-read.js";
 import { hidePublicTestData } from "../../../_internal/server/features/tester/visibility.js";
 function sp(params, key) {
@@ -10,7 +11,7 @@ function sp(params, key) {
     return Array.isArray(v) ? v[0] ?? "" : v ?? "";
 }
 export async function BlogIndexPageView({ searchParams = {} }) {
-    const sort = sp(searchParams, "sort") || "-publishedAt";
+    const sort = sp(searchParams, "sort") || BLOG_DEFAULT_PUBLIC_SORT;
     const page = Number(sp(searchParams, "page")) || 1;
     const pageSize = Number(sp(searchParams, "pageSize")) || 24;
     const category = sp(searchParams, "category");

package/dist/features/blog/repository/blog.repository.d.ts

@@ -55,6 +55,10 @@ declare class BlogRepository extends BaseRepository<BlogPostDocument> {
             canFilter: boolean;
             canSort: boolean;
         };
+        isPinned: {
+            canFilter: boolean;
+            canSort: boolean;
+        };
         readTimeMinutes: {
             canFilter: boolean;
             canSort: boolean;

package/dist/features/blog/repository/blog.repository.js

@@ -223,6 +223,11 @@ BlogRepository.SIEVE_FIELDS = {
     authorName: { canFilter: true, canSort: true },
     authorId: { canFilter: true, canSort: false },
     isFeatured: { canFilter: true, canSort: false },
+    // canSort because it is the FIRST key of the default sort
+    // `-isPinned,-publishedAt`. A `canSort: false` field is silently dropped by
+    // sievejs (Root Cause #63), which would leave the index ordered by date
+    // alone and the pin doing nothing, with no error anywhere.
+    isPinned: { canFilter: true, canSort: true },
     readTimeMinutes: { canFilter: true, canSort: true },
     views: { canFilter: true, canSort: true },
     publishedAt: { canFilter: true, canSort: true, parseValue: parseSieveDateValue },

package/dist/features/blog/schemas/blog-form.d.ts

@@ -47,6 +47,7 @@ export declare const blogDraftSchema: z.ZodObject<{
     publishedAt: z.ZodString;
     authorName: z.ZodString;
     isFeatured: z.ZodBoolean;
+    isPinned: z.ZodBoolean;
 }, "strip", z.ZodTypeAny, {
     status: "published" | "draft" | "archived";
     title: string;
@@ -60,6 +61,7 @@ export declare const blogDraftSchema: z.ZodObject<{
     excerpt: string;
     coverImage: string;
     authorName: string;
+    isPinned: boolean;
     metaTitle: string;
     metaDescription: string;
 }, {
@@ -75,6 +77,7 @@ export declare const blogDraftSchema: z.ZodObject<{
     excerpt: string;
     coverImage: string;
     authorName: string;
+    isPinned: boolean;
     metaTitle: string;
     metaDescription: string;
 }>;

package/dist/features/blog/schemas/blog-form.js

@@ -97,4 +97,5 @@ export const blogDraftSchema = z.object({
     }),
     authorName: annotate(z.string(), { section: "publish", order: 3, row: "pair" }),
     isFeatured: annotate(z.boolean(), { section: "publish", order: 4, row: "quarter" }),
+    isPinned: annotate(z.boolean(), { section: "publish", order: 5, row: "quarter" }),
 });

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

@@ -29,6 +29,23 @@ export interface BlogPostDocument extends BaseDocument {
     category: BlogPostCategory;
     tags: string[];
     isFeatured: boolean;
+    /**
+     * Keeps the post at the top of the blog index and the homepage
+     * `blog-articles` section, above newer posts.
+     *
+     * 🛑 REQUIRED, not optional, and that is load-bearing. The default sort is
+     * `-isPinned,-publishedAt`, and Firestore EXCLUDES a document that lacks an
+     * `orderBy` field (Root Cause #100) — so an optional `isPinned` would drop
+     * every pre-existing post out of its own index, silently, with a 200.
+     * A `mapDoc` default cannot rescue it either: that is a read-side fixup and
+     * a query never sees it (Root Cause #101). Every row needs a real `false`
+     * written, which is why the seed carries it explicitly.
+     *
+     * Distinct from `isFeatured` on purpose: featured drives the badge and the
+     * featured-card treatment, and there are several featured posts. Overloading
+     * it would make "featured" and "first" the same decision.
+     */
+    isPinned: boolean;
     status: BlogPostStatus;
     publishedAt?: Date;
     authorId: string;
@@ -40,7 +57,25 @@ export interface BlogPostDocument extends BaseDocument {
     metaDescription?: string;
 }
 export declare const BLOG_POSTS_COLLECTION: "blogPosts";
-export declare const BLOG_POSTS_INDEXED_FIELDS: readonly ["searchTxt", "status", "publishedAt", "isFeatured", "category", "slug"];
+export declare const BLOG_POSTS_INDEXED_FIELDS: readonly ["searchTxt", "status", "publishedAt", "isFeatured", "isPinned", "category", "slug"];
+/**
+ * The default ordering for every PUBLIC blog surface — the `/blog` index, the
+ * `/api/blog` route that refetches it, and the homepage `blog-articles` feed.
+ *
+ * 🛑 ONE constant, three consumers, deliberately. The SSR view hands its result
+ * to the listing hook as `initialData`, and that hook sets `staleTime: Infinity`
+ * when given SSR data — so if the route's default sort differed from the view's
+ * by even a character, the first paint would be frozen in one order while the
+ * query key described another (Root Cause #30). Three literals is how that
+ * drift happens; one import is how it cannot.
+ *
+ * `isPinned` leads so pinned posts sit above newer ones. Needs the composite
+ * indexes on (status, isPinned DESC, publishedAt DESC) and its category /
+ * isFeatured / searchTxt variants — a multi-field sieve sort becomes two
+ * `orderBy` calls, and a missing index is a silent FAILED_PRECONDITION that
+ * every caller swallows into an empty page (Root Cause #2 / #59).
+ */
+export declare const BLOG_DEFAULT_PUBLIC_SORT: "-isPinned,-publishedAt";
 export declare const BLOG_POST_FIELDS: {
     /** Word-prefix search tokens. Derived on write by `buildSearchTxtFor`. */
     readonly SEARCH_TXT: "searchTxt";
@@ -56,6 +91,7 @@ export declare const BLOG_POST_FIELDS: {
     readonly CATEGORY: "category";
     readonly TAGS: "tags";
     readonly IS_FEATURED: "isFeatured";
+    readonly IS_PINNED: "isPinned";
     readonly STATUS: "status";
     readonly PUBLISHED_AT: "publishedAt";
     readonly AUTHOR_ID: "authorId";
@@ -89,6 +125,7 @@ export type BlogPostUpdateInput = Partial<Omit<BlogPostDocument, "id" | "created
 export declare const blogPostQueryHelpers: {
     readonly published: () => readonly ["status", "==", BlogPostStatus];
     readonly featured: () => readonly ["isFeatured", "==", true];
+    readonly pinned: () => readonly ["isPinned", "==", true];
     readonly byCategory: (category: BlogPostCategory) => readonly ["category", "==", BlogPostCategory];
     readonly bySlug: (slug: string) => readonly ["slug", "==", string];
     readonly byAuthor: (authorId: string) => readonly ["authorId", "==", string];

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

@@ -14,9 +14,28 @@ export const BLOG_POSTS_INDEXED_FIELDS = [
     "status",
     "publishedAt",
     "isFeatured",
+    "isPinned",
     "category",
     "slug",
 ];
+/**
+ * The default ordering for every PUBLIC blog surface — the `/blog` index, the
+ * `/api/blog` route that refetches it, and the homepage `blog-articles` feed.
+ *
+ * 🛑 ONE constant, three consumers, deliberately. The SSR view hands its result
+ * to the listing hook as `initialData`, and that hook sets `staleTime: Infinity`
+ * when given SSR data — so if the route's default sort differed from the view's
+ * by even a character, the first paint would be frozen in one order while the
+ * query key described another (Root Cause #30). Three literals is how that
+ * drift happens; one import is how it cannot.
+ *
+ * `isPinned` leads so pinned posts sit above newer ones. Needs the composite
+ * indexes on (status, isPinned DESC, publishedAt DESC) and its category /
+ * isFeatured / searchTxt variants — a multi-field sieve sort becomes two
+ * `orderBy` calls, and a missing index is a silent FAILED_PRECONDITION that
+ * every caller swallows into an empty page (Root Cause #2 / #59).
+ */
+export const BLOG_DEFAULT_PUBLIC_SORT = "-isPinned,-publishedAt";
 export const BLOG_POST_FIELDS = {
     /** Word-prefix search tokens. Derived on write by `buildSearchTxtFor`. */
     SEARCH_TXT: "searchTxt",
@@ -32,6 +51,7 @@ export const BLOG_POST_FIELDS = {
     CATEGORY: "category",
     TAGS: "tags",
     IS_FEATURED: "isFeatured",
+    IS_PINNED: "isPinned",
     STATUS: "status",
     PUBLISHED_AT: "publishedAt",
     AUTHOR_ID: "authorId",
@@ -64,6 +84,7 @@ export const DEFAULT_BLOG_POST_DATA = {
     category: "news",
     tags: [],
     isFeatured: false,
+    isPinned: false,
     status: "draft",
     authorId: "",
     authorName: "",
@@ -80,6 +101,7 @@ export const BLOG_POST_PUBLIC_FIELDS = [
     "category",
     "tags",
     "isFeatured",
+    "isPinned",
     "status",
     "publishedAt",
     "authorName",
@@ -94,6 +116,7 @@ export const BLOG_POST_PUBLIC_FIELDS = [
 export const blogPostQueryHelpers = {
     published: () => ["status", "==", "published"],
     featured: () => ["isFeatured", "==", true],
+    pinned: () => ["isPinned", "==", true],
     byCategory: (category) => ["category", "==", category],
     bySlug: (slug) => ["slug", "==", slug],
     byAuthor: (authorId) => ["authorId", "==", authorId],

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

@@ -99,6 +99,7 @@ export declare const blogPostFirestoreSchema: z.ZodObject<{
     category: z.ZodString;
     tags: z.ZodArray<z.ZodString, "many">;
     isFeatured: z.ZodBoolean;
+    isPinned: z.ZodBoolean;
     status: z.ZodEnum<["draft", "published", "archived"]>;
     publishedAt: z.ZodOptional<z.ZodUnion<[z.ZodDate, z.ZodString, z.ZodObject<{
         toDate: z.ZodFunction<z.ZodTuple<[], z.ZodUnknown>, z.ZodDate>;
@@ -134,6 +135,7 @@ export declare const blogPostFirestoreSchema: z.ZodObject<{
     authorId: string;
     authorName: string;
     readTimeMinutes: number;
+    isPinned: boolean;
     publishedAt?: string | Date | z.objectOutputType<{
         toDate: z.ZodFunction<z.ZodTuple<[], z.ZodUnknown>, z.ZodDate>;
     }, z.ZodTypeAny, "passthrough"> | undefined;
@@ -187,6 +189,7 @@ export declare const blogPostFirestoreSchema: z.ZodObject<{
     authorId: string;
     authorName: string;
     readTimeMinutes: number;
+    isPinned: boolean;
     publishedAt?: string | Date | z.objectInputType<{
         toDate: z.ZodFunction<z.ZodTuple<[], z.ZodUnknown>, z.ZodDate>;
     }, z.ZodTypeAny, "passthrough"> | undefined;
@@ -343,6 +346,7 @@ export declare const blogPostSchema: z.ZodObject<{
     category: z.ZodEnum<["news", "tips", "guides", "updates", "community"]>;
     tags: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
     isFeatured: z.ZodOptional<z.ZodBoolean>;
+    isPinned: z.ZodOptional<z.ZodBoolean>;
     status: z.ZodEnum<["draft", "published", "archived"]>;
     publishedAt: z.ZodOptional<z.ZodString>;
     authorId: z.ZodOptional<z.ZodString>;
@@ -401,6 +405,7 @@ export declare const blogPostSchema: z.ZodObject<{
     authorId?: string | undefined;
     authorName?: string | undefined;
     readTimeMinutes?: number | undefined;
+    isPinned?: boolean | undefined;
     authorAvatar?: string | undefined;
     metaTitle?: string | undefined;
     metaDescription?: string | undefined;
@@ -430,6 +435,7 @@ export declare const blogPostSchema: z.ZodObject<{
     authorId?: string | undefined;
     authorName?: string | undefined;
     readTimeMinutes?: number | undefined;
+    isPinned?: boolean | undefined;
     additionalImages?: {
         type: "video" | "image" | "file";
         url: string;

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

@@ -18,6 +18,7 @@ export const blogPostFirestoreSchema = z.object({
     category: z.string(),
     tags: z.array(z.string()),
     isFeatured: z.boolean(),
+    isPinned: z.boolean(),
     status: blogPostStatusEnumSchema,
     publishedAt: firestoreDateSchema.optional(),
     authorId: z.string(),
@@ -72,6 +73,7 @@ export const blogPostSchema = z.object({
     category: blogPostCategorySchema,
     tags: z.array(z.string()).optional(),
     isFeatured: z.boolean().optional(),
+    isPinned: z.boolean().optional(),
     status: blogPostStatusSchema,
     publishedAt: z.string().optional(),
     authorId: z.string().optional(),

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

@@ -15,6 +15,8 @@ export interface BlogPost {
     category: BlogPostCategory;
     tags?: string[];
     isFeatured?: boolean;
+    /** Keeps the post above newer ones on the blog index and homepage. */
+    isPinned?: boolean;
     status: BlogPostStatus;
     publishedAt?: string;
     authorId?: string;

package/dist/features/cart/components/CartPriceBreakdown.d.ts

@@ -1,4 +1,5 @@
 import React from "react";
+import type { FeeDerivations } from "../../../_internal/shared/fees/explain";
 /**
  * The aggregate price breakdown shown in the cart's expandable preview and in
  * the checkout Order Summary.
@@ -86,5 +87,15 @@ export interface CartPriceBreakdownProps {
     errorNote?: React.ReactNode;
     isLoading?: boolean;
     className?: string;
+    /**
+     * Per-line "why am I paying this" disclosures, built by the
+     * `explain*` helpers in `_internal/shared/fees/explain`.
+     *
+     * 🛑 Optional, and an absent entry renders no disclosure rather than a
+     * placeholder. The cart renders this breakdown for a signed-out guest with
+     * no server preview at all — a line that cannot be explained must say
+     * nothing, never "we could not work this out", which reads as a fault.
+     */
+    derivations?: FeeDerivations;
 }
-export declare function CartPriceBreakdown({ preview, itemCount, currency, unavailableNote, fallbackSubtotal, errorNote, isLoading, className, }: CartPriceBreakdownProps): React.JSX.Element;
+export declare function CartPriceBreakdown({ preview, itemCount, currency, unavailableNote, fallbackSubtotal, errorNote, isLoading, className, derivations, }: CartPriceBreakdownProps): React.JSX.Element;

package/dist/features/cart/components/CartPriceBreakdown.js

@@ -1,15 +1,34 @@
 "use client";
 import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
-import { Div, Row, Stack, Text } from "../../../ui/index.js";
+import { Details, Div, Row, Stack, Summary, Text } from "../../../ui/index.js";
 import { formatCurrency } from "../../../utils/number.formatter.js";
-function Line({ label, amount, tone = "muted", strong = false, }) {
-    return (_jsxs(Row, { align: "center", justify: "between", gap: "sm", className: "min-w-0", children: [_jsx(Text, { size: "sm", color: tone, weight: strong ? "semibold" : undefined, className: "min-w-0", truncate: 1, children: label }), _jsx(Text, { size: "sm", color: tone, weight: strong ? "semibold" : undefined, className: "flex-shrink-0 tabular-nums", children: amount })] }));
+/**
+ * The "how is this calculated?" disclosure under a fee line.
+ *
+ * 🛑 Collapsed by default, and that is the whole design. An unexplained charge
+ * is untrustworthy, but five expanded derivations turn the Order Summary into
+ * a wall of arithmetic at the moment a buyer is deciding to pay. The
+ * obligation is that the answer is *available at the point of the charge* —
+ * not that it is shouted.
+ *
+ * A native `<details>` rather than a tooltip or a modal: it works before
+ * hydration, it is keyboard-reachable for free, and it does not cover the
+ * number it is explaining.
+ */
+function Derivation({ derivation }) {
+    return (_jsxs(Details, { tone: "muted", padding: "sm", rounded: "md", children: [_jsx(Summary, { size: "xs", color: "muted", children: "How is this calculated?" }), _jsxs(Stack, { gap: "xs", className: "pt-[var(--appkit-space-2)]", children: [_jsx(Text, { size: "xs", color: "muted", children: derivation.summary }), derivation.steps.map((step, i) => (_jsx(Text, { size: "xs", color: "faint", className: "tabular-nums", children: step }, i)))] })] }));
+}
+function Line({ label, amount, tone = "muted", strong = false, derivation, }) {
+    const row = (_jsxs(Row, { align: "center", justify: "between", gap: "sm", className: "min-w-0", children: [_jsx(Text, { size: "sm", color: tone, weight: strong ? "semibold" : undefined, className: "min-w-0", truncate: 1, children: label }), _jsx(Text, { size: "sm", color: tone, weight: strong ? "semibold" : undefined, className: "flex-shrink-0 tabular-nums", children: amount })] }));
+    if (!derivation)
+        return row;
+    return (_jsxs(Stack, { gap: "xs", children: [row, _jsx(Derivation, { derivation: derivation })] }));
 }
 /** "Shipping (2 stores)" — only qualifies when more than one store contributes. */
 function withStoreCount(label, count) {
     return count > 1 ? `${label} (${count} stores)` : label;
 }
-export function CartPriceBreakdown({ preview, itemCount, currency = "INR", unavailableNote, fallbackSubtotal = 0, errorNote, isLoading = false, className = "", }) {
+export function CartPriceBreakdown({ preview, itemCount, currency = "INR", unavailableNote, fallbackSubtotal = 0, errorNote, isLoading = false, className = "", derivations, }) {
     const money = (value) => formatCurrency(value, currency);
     if (!preview) {
         return (_jsxs(Stack, { gap: "xs", className: className, children: [_jsx(Line, { label: itemCount !== undefined ? `Subtotal (${itemCount} item${itemCount !== 1 ? "s" : ""})` : "Subtotal", amount: money(fallbackSubtotal) }), (errorNote ?? unavailableNote) && (_jsx(Text, { size: "xs", color: errorNote ? "error" : "muted", children: errorNote ?? unavailableNote }))] }));
@@ -21,7 +40,7 @@ export function CartPriceBreakdown({ preview, itemCount, currency = "INR", unava
     const subtotalLabel = itemCount !== undefined
         ? `Subtotal (${itemCount} item${itemCount !== 1 ? "s" : ""}${storeCount > 1 ? `, ${storeCount} stores` : ""})`
         : "Subtotal";
-    return (_jsxs(Stack, { gap: "xs", className: className, children: [_jsx(Line, { label: subtotalLabel, amount: money(preview.subtotal) }), preview.shippingFee > 0 && (_jsx(Line, { label: withStoreCount("Shipping", storeCount), amount: money(preview.shippingFee) })), preview.codHandlingFee > 0 && (_jsx(Line, { label: "COD handling fee", amount: money(preview.codHandlingFee) })), preview.giftWrapFee > 0 && (_jsx(Line, { label: withStoreCount("Gift wrap", countCharged((s) => s.giftWrapFee)), amount: money(preview.giftWrapFee) })), preview.shipmentProtectionFee > 0 && (_jsx(Line, { label: withStoreCount("Shipment protection", countCharged((s) => s.shipmentProtectionFee)), amount: money(preview.shipmentProtectionFee) })), preview.saleProtectionFee > 0 && (_jsx(Line, { label: withStoreCount("Sale protection", countCharged((s) => s.saleProtectionFee)), amount: money(preview.saleProtectionFee) })), preview.emiSurcharge > 0 && (_jsx(Line, { label: "EMI surcharge", amount: money(preview.emiSurcharge) })), preview.sharedPurchaseFee > 0 && (_jsx(Line, { label: withStoreCount("Split delivery", countCharged((s) => s.sharedPurchaseFee)), amount: money(preview.sharedPurchaseFee) })), preview.platformFee > 0 && _jsx(Line, { label: "Platform fee", amount: money(preview.platformFee) }), preview.gstOnFee > 0 && (_jsx(Line, { label: "GST on platform fee", amount: money(preview.gstOnFee) })), preview.couponDiscount > 0 && (_jsx(Line, { label: "Coupon discount", amount: `−${money(preview.couponDiscount)}`, tone: "success" })), _jsx(Div, { border: "top-subtle", paddingY: "t-sm", children: _jsx(Line, { label: "Total", amount: money(preview.total), tone: "primary", strong: preview.pointsApplied <= 0 }) }), preview.pointsApplied > 0 && (_jsxs(_Fragment, { children: [_jsx(Line, { label: `Points applied (${preview.pointsApplied.toLocaleString("en-IN")} pts)`, amount: `−${money(preview.pointsApplied)}`, tone: "success" }), _jsx(Div, { border: "top-subtle", paddingY: "t-sm", children: _jsx(Line, { label: "Amount due", amount: money(preview.amountDue), tone: "primary", strong: true }) })] })), preview.pointsApplied > 0 && preview.pointsBalance > preview.pointsApplied && (_jsxs(Text, { size: "xs", color: "muted", children: [(preview.pointsBalance - preview.pointsApplied).toLocaleString("en-IN"), " points stay in your balance \u2014 up to half of an order can be paid with points."] })), preview.pointsApplied === 0 && preview.pointsBalance > 0 && (_jsx(Text, { size: "xs", color: "muted", children: preview.stores.some((s) => s.acceptsPoints)
+    return (_jsxs(Stack, { gap: "xs", className: className, children: [_jsx(Line, { label: subtotalLabel, amount: money(preview.subtotal) }), preview.shippingFee > 0 && (_jsx(Line, { label: withStoreCount("Shipping", storeCount), amount: money(preview.shippingFee) })), preview.codHandlingFee > 0 && (_jsx(Line, { label: "COD handling fee", amount: money(preview.codHandlingFee), derivation: derivations?.codHandlingFee })), preview.giftWrapFee > 0 && (_jsx(Line, { label: withStoreCount("Gift wrap", countCharged((s) => s.giftWrapFee)), amount: money(preview.giftWrapFee) })), preview.shipmentProtectionFee > 0 && (_jsx(Line, { label: withStoreCount("Shipment protection", countCharged((s) => s.shipmentProtectionFee)), amount: money(preview.shipmentProtectionFee) })), preview.saleProtectionFee > 0 && (_jsx(Line, { label: withStoreCount("Sale protection", countCharged((s) => s.saleProtectionFee)), amount: money(preview.saleProtectionFee) })), preview.emiSurcharge > 0 && (_jsx(Line, { label: "EMI surcharge", amount: money(preview.emiSurcharge), derivation: derivations?.emiSurcharge })), preview.sharedPurchaseFee > 0 && (_jsx(Line, { label: withStoreCount("Split delivery", countCharged((s) => s.sharedPurchaseFee)), amount: money(preview.sharedPurchaseFee) })), preview.platformFee > 0 && (_jsx(Line, { label: "Platform fee", amount: money(preview.platformFee), derivation: derivations?.platformFee })), preview.gstOnFee > 0 && (_jsx(Line, { label: "GST on platform fee", amount: money(preview.gstOnFee), derivation: derivations?.gstOnFee })), preview.couponDiscount > 0 && (_jsx(Line, { label: "Coupon discount", amount: `−${money(preview.couponDiscount)}`, tone: "success" })), _jsx(Div, { border: "top-subtle", paddingY: "t-sm", children: _jsx(Line, { label: "Total", amount: money(preview.total), tone: "primary", strong: preview.pointsApplied <= 0 }) }), preview.pointsApplied > 0 && (_jsxs(_Fragment, { children: [_jsx(Line, { label: `Points applied (${preview.pointsApplied.toLocaleString("en-IN")} pts)`, amount: `−${money(preview.pointsApplied)}`, tone: "success" }), _jsx(Div, { border: "top-subtle", paddingY: "t-sm", children: _jsx(Line, { label: "Amount due", amount: money(preview.amountDue), tone: "primary", strong: true }) })] })), preview.pointsApplied > 0 && preview.pointsBalance > preview.pointsApplied && (_jsxs(Text, { size: "xs", color: "muted", children: [(preview.pointsBalance - preview.pointsApplied).toLocaleString("en-IN"), " points stay in your balance \u2014 up to half of an order can be paid with points."] })), preview.pointsApplied === 0 && preview.pointsBalance > 0 && (_jsx(Text, { size: "xs", color: "muted", children: preview.stores.some((s) => s.acceptsPoints)
                     ? "Your points could not be applied to this order."
                     : storeCount > 1
                         ? "None of these sellers accepts points."

package/dist/features/cart/repository/cart.repository.d.ts

@@ -147,6 +147,20 @@ export declare class CartRepository extends BaseRepository<CartDocument> {
      * and keeping both shapes invites a reader that handles only one. Same
      * reasoning as `setStoreAddons` directly above.
      */
+    /**
+     * Set or clear the instalment plan.
+     *
+     * 🛑 `null` DELETES the field rather than storing `{ optIn: false }`. The
+     * schema's rule is that absent means "no instalments", so a second
+     * representation of the same state is one more thing every reader has to
+     * get right (Root Cause #42's shape). `tenureMonths` is stored verbatim and
+     * validated against the live `emi.tenureOptions` at order time — the admin
+     * can change those options after a cart was saved, so validating here would
+     * freeze a tenure that is no longer offered.
+     */
+    setEmiPlan(userId: string, plan: {
+        tenureMonths: number;
+    } | null): Promise<void>;
     setUseAllPoints(userId: string, useAllPoints: boolean): Promise<void>;
     /**
      * Cloud Functions: return refs of stale carts not updated within TTL.

package/dist/features/cart/repository/cart.repository.js

@@ -608,6 +608,26 @@ export class CartRepository extends BaseRepository {
      * and keeping both shapes invites a reader that handles only one. Same
      * reasoning as `setStoreAddons` directly above.
      */
+    /**
+     * Set or clear the instalment plan.
+     *
+     * 🛑 `null` DELETES the field rather than storing `{ optIn: false }`. The
+     * schema's rule is that absent means "no instalments", so a second
+     * representation of the same state is one more thing every reader has to
+     * get right (Root Cause #42's shape). `tenureMonths` is stored verbatim and
+     * validated against the live `emi.tenureOptions` at order time — the admin
+     * can change those options after a cart was saved, so validating here would
+     * freeze a tenure that is no longer offered.
+     */
+    async setEmiPlan(userId, plan) {
+        await this.db
+            .collection(this.collection)
+            .doc(userId)
+            .set({
+            emiPlan: plan ? { tenureMonths: plan.tenureMonths } : FieldValue.delete(),
+            updatedAt: new Date(),
+        }, { merge: true });
+    }
     async setUseAllPoints(userId, useAllPoints) {
         await this.db
             .collection(this.collection)

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

@@ -331,6 +331,30 @@ export interface CartDocument extends BaseDocument {
      * (D46). A number was the wrong shape as well as the wrong place.
      */
     useAllPoints?: boolean;
+    /**
+     * "Pay in instalments", with the chosen tenure — an opt-in ON THE ORDER,
+     * orthogonal to how the token is tendered.
+     *
+     * 🛑 It lives HERE, on the cart, for exactly the reason `storeAddons` does:
+     * the online path creates the gateway order in one request
+     * (`/api/payment/create-order`, which decides the CAPTURE amount) and the
+     * order document in a later one (`/api/payment/verify`). A choice carried in
+     * a request body cannot be read by both, so the two would be free to
+     * disagree about how much of the total is deferred — and the difference is
+     * money captured that the order does not record (the D37/D38/D40 class).
+     *
+     * `useAllPoints` is the precedent and the shape is deliberately the same: a
+     * durable selection the server re-reads, never a client-supplied amount.
+     *
+     * Absent means a plain full-price order, which is why it is written with
+     * `FieldValue.delete()` rather than `{ optIn: false }` — a stored false and
+     * an absent field must not be two ways of saying the same thing.
+     */
+    emiPlan?: CartEmiPlan;
+}
+/** The buyer's instalment selection. `tenureMonths` is validated against the live `emi.tenureOptions` at order time, never here. */
+export interface CartEmiPlan {
+    tenureMonths: number;
 }
 export declare const CART_COLLECTION: "carts";
 export declare const CART_INDEXED_FIELDS: string[];