@mohasinac/appkit 4.23.0 → 4.25.0

package/dist/_internal/server/features/bundles/actions.js

@@ -15,6 +15,7 @@
 import { NotFoundError, ValidationError } from "../../../../errors";
 import { categoriesRepository } from "../../../../repositories";
 import { cartRepository } from "../../../../features/cart/repository/cart.repository";
+import { assertCanAddNewItems } from "../../../../features/cart/actions/cart-actions";
 import { getDefaultCurrency } from "../../../../core/baseline-resolver";
 export async function addBundleToCartAction(userId, bundleSlug) {
     if (!userId)
@@ -32,6 +33,12 @@ export async function addBundleToCartAction(userId, bundleSlug) {
     if (!bundle.bundlePrice || bundle.bundlePrice < 1) {
         throw new ValidationError("Bundle price is not configured");
     }
+    // Bundles bypass `addItemToCart`'s capability gate deliberately (a bundle's
+    // `listingType: "standard"` is a lie told to satisfy it — `bundleRule` is
+    // `cartEligible: false`). The LANE gate is not optional though, and this path
+    // silently skipped it: a buyer with an unpaid auction win could keep shopping
+    // by adding bundles.
+    await assertCanAddNewItems(userId);
     await cartRepository.addItem(userId, {
         productId: bundle.id,
         productTitle: bundle.name,

package/dist/_internal/server/features/checkout/actions.js

@@ -14,7 +14,7 @@ import { ORDER_FIELDS } from "../../../../constants/field-names";
 import { serverLogger } from "../../../../monitoring";
 import { unitOfWork, siteSettingsRepository, userRepository, storeRepository, couponsRepository, claimedCouponsRepository, addressesRepository, productRepository, } from "../../../../repositories";
 import { calculateGst } from "../../../shared/fees/calculator";
-import { computePreOrderDepositAmount, unitPriceFor } from "../../../shared/checkout/order-math";
+import { computePreOrderDepositAmount, lineTotalFor, unitPriceFor } from "../../../shared/checkout/order-math";
 import { failedCheckoutRepository } from "../../../../features/checkout/repository/failed-checkout.repository";
 import { sendOrderConfirmationEmail } from "../../../../features/contact/server";
 import { splitCartIntoOrderGroups } from "../../../../features/orders/index";
@@ -26,7 +26,7 @@ import { getAdminDb, getAdminRealtimeDb, RTDB_PATHS, } from "../../../../provide
 import { PRODUCT_COLLECTION, PRODUCT_CODES_SUBCOLLECTION } from "../../../../features/products/schemas/firestore";
 import { CART_COLLECTION } from "../../../../features/cart/schemas/index";
 // S-SBUNI-RULES 2026-05-13 — bundle cart-line stock fan-out helpers.
-import { getCartItemMemberIds, getExpandedDecrements, bucketCartItemsByStock, } from "./bundle-expansion";
+import { getCartItemMemberIds, getExpandedDecrements, bucketCartItemsByStock, isMultiMemberLine, } from "./bundle-expansion";
 import { OrderStatusValues, PaymentStatusValues, PaymentMethodValues, OutOfStockPolicyValues, } from "../../../../features/orders/schemas/index";
 import { getDefaultCurrency } from "../../../../core/index";
 import { verifyPaymentSignatureWithKeys, fetchRazorpayOrder, paiseToRupees, } from "../../../../providers/payment-razorpay/index";
@@ -374,7 +374,7 @@ async function createOrderForGroup(group, orderType, ctx) {
     // Add-ons are this store's choice, not the cart's — see OrderGroupContext.
     const { whatsappNotifyAddon = false, giftWrapAddon = false, giftWrapMessage, shipmentProtectionAddon = false, } = storeAddons?.[firstItem.storeId] ?? {};
     const { platformFee = 0, gstOnFee: platformFeeGst = 0 } = platformFeeByStore.get(firstItem.storeId) ?? {};
-    const groupTotal = group.reduce((sum, { item, product }) => sum + unitPriceFor(item, product) * item.quantity, 0);
+    const groupTotal = group.reduce((sum, { item, product }) => sum + lineTotalFor(item, product), 0);
     // S-SBUNI-RULES 2026-05-13 — order-item decoration via rule registry.
     const orderItems = group.map(({ item, product }) => {
         const lt = (product.listingType ?? "standard");
@@ -415,7 +415,7 @@ async function createOrderForGroup(group, orderType, ctx) {
         let taxableAmount = 0;
         let gstAmount = 0;
         for (const { item, product } of group) {
-            const lineTotal = unitPriceFor(item, product) * item.quantity;
+            const lineTotal = lineTotalFor(item, product);
             const rate = product.gstRate ?? 0;
             if (rate > 0) {
                 taxableAmount += lineTotal;
@@ -756,8 +756,9 @@ export async function createCheckoutOrderAction(input) {
             const availableItems = [];
             for (const { item, product } of bucketed.available) {
                 // S-SBUNI-RULES 2026-05-13 — sync preflight (prize-pool cap, pre-order
-                // quota) via rule registry. Bundles skip — they bypass the cart path.
-                if (!item.bundleProductIds?.length) {
+                // quota) via rule registry. Multi-member lines skip: their listingType
+                // describes the wrapper, not the members.
+                if (!isMultiMemberLine(item)) {
                     runSyncPreflight([{ item, product }], paymentMethod);
                 }
                 availableItems.push({ item, product });
@@ -774,8 +775,16 @@ export async function createCheckoutOrderAction(input) {
                 }
             }
             if (availableItems.length > 0) {
-                const orderedProductIds = new Set(availableItems.map((a) => a.item.productId));
-                const remainingCartItems = cart.items.filter((ci) => !orderedProductIds.has(ci.productId));
+                // Clear by LINE identity, not by productId. `itemId` is what uniquely
+                // identifies a line; `productId` is not unique across lines and is not
+                // even a product id on a bundle/group line (it points at the bundle
+                // category, or at the group parent — which is itself purchasable). So
+                // matching on it deleted every OTHER line that happened to share the
+                // value: a loose "Set" parent sitting beside a group line built from
+                // that same group, or two lines of one product, both vanished when only
+                // one was ordered.
+                const orderedItemIds = new Set(availableItems.map((a) => a.item.itemId));
+                const remainingCartItems = cart.items.filter((ci) => !orderedItemIds.has(ci.itemId));
                 const cartRef = db.collection(CART_COLLECTION).doc(uid);
                 tx.set(cartRef, {
                     items: remainingCartItems,
@@ -818,13 +827,13 @@ export async function createCheckoutOrderAction(input) {
     const orderIds = [];
     let total = 0;
     const emailsToSend = [];
-    const cartSubtotal = orderGroups.reduce((s, { items: g }) => s + g.reduce((gs, { item, product }) => gs + unitPriceFor(item, product) * item.quantity, 0), 0);
+    const cartSubtotal = orderGroups.reduce((s, { items: g }) => s + g.reduce((gs, { item, product }) => gs + lineTotalFor(item, product), 0), 0);
     const couponUsageAccumulator = new Map();
     // One commission on one transaction, capped, then apportioned across the
     // orders this cart splits into — see allocateCheckoutFees.
     const platformFeeByStore = allocateCheckoutFees(orderGroups.map(({ items: g }) => [
         g[0].item.storeId,
-        g.reduce((sum, { item, product }) => sum + unitPriceFor(item, product) * item.quantity, 0),
+        g.reduce((sum, { item, product }) => sum + lineTotalFor(item, product), 0),
     ]), computeCheckoutFees(cartSubtotal, commissions));
     const groupCtx = {
         paymentMethod,
@@ -922,7 +931,7 @@ export async function previewCheckoutPricing(input) {
     }
     const checks = cartItems.map((item) => ({ item, product: productById.get(item.productId) ?? null }));
     const orderGroups = splitCartIntoOrderGroups(checks);
-    const cartSubtotal = orderGroups.reduce((s, { items: g }) => s + g.reduce((gs, { item, product }) => gs + unitPriceFor(item, product) * item.quantity, 0), 0);
+    const cartSubtotal = orderGroups.reduce((s, { items: g }) => s + g.reduce((gs, { item, product }) => gs + lineTotalFor(item, product), 0), 0);
     // Same re-validation the real order placement runs, so the preview never
     // shows a discount the order won't actually honour.
     const { coupons: appliedCoupons } = await revalidateAppliedCoupons(cart.appliedCoupons ?? [], checks, uid);
@@ -932,7 +941,7 @@ export async function previewCheckoutPricing(input) {
     const stores = [];
     for (const { items: group } of orderGroups) {
         const firstItem = group[0].item;
-        const groupTotal = group.reduce((sum, { item, product }) => sum + unitPriceFor(item, product) * item.quantity, 0);
+        const groupTotal = group.reduce((sum, { item, product }) => sum + lineTotalFor(item, product), 0);
         const { shippingFee: groupShippingFee, storeState } = await resolveShippingCost(firstItem.storeId);
         // Add-ons are per store, read off the cart document — the same entry
         // createOrderForGroup will read when the order is actually placed.
@@ -948,13 +957,13 @@ export async function previewCheckoutPricing(input) {
         if (siteSettings?.gst?.enabled && resolvedAddress?.state) {
             const intraState = !!storeState && storeState === resolvedAddress.state;
             for (const { item, product } of group) {
-                const lineTotal = unitPriceFor(item, product) * item.quantity;
+                const lineTotal = lineTotalFor(item, product);
                 const rate = product?.gstRate ?? 0;
                 if (rate > 0)
                     groupGstAmount += calculateGst(rate, intraState, lineTotal).gstAmount;
             }
         }
-        const groupLines = group.map(({ item, product }) => ({ itemId: item.itemId, lineTotal: unitPriceFor(item, product) * item.quantity }));
+        const groupLines = group.map(({ item, product }) => ({ itemId: item.itemId, lineTotal: lineTotalFor(item, product) }));
         const { couponDiscount: groupCouponDiscount } = computeGroupCouponDiscount(appliedCoupons, groupLines, groupTotal, cartSubtotal, firstItem.storeId);
         stores.push({
             storeId: firstItem.storeId,
@@ -1131,12 +1140,12 @@ async function refundDroppedItemsForRazorpayCheckout(input) {
 async function createRazorpayGroupOrder(group, orderType, ctx) {
     const { appliedCoupons, cartSubtotal, storeAddons, platformFeeByStore, siteSettings, uid, userName, userEmail, razorpay_order_id, razorpay_payment_id, razorpay_signature, shippingAddress, notes, outOfStockPolicy, unavailablePaid, orderIds, emailsToSend, couponUsageAccumulator, } = ctx;
     const firstItem = group[0].item;
-    const groupTotal = group.reduce((sum, { item, product }) => sum + unitPriceFor(item, product) * item.quantity, 0);
+    const groupTotal = group.reduce((sum, { item, product }) => sum + lineTotalFor(item, product), 0);
     // Reuses the same store/seller lookup as the COD/UPI path above instead
     // of re-implementing it inline — was two sequential findById calls per
     // seller group here, duplicated from resolveShippingCost.
     const { shippingFee, storeOwnerId } = await resolveShippingCost(firstItem.storeId);
-    const groupLines = group.map(({ item, product }) => ({ itemId: item.itemId, lineTotal: unitPriceFor(item, product) * item.quantity }));
+    const groupLines = group.map(({ item, product }) => ({ itemId: item.itemId, lineTotal: lineTotalFor(item, product) }));
     const { couponDiscount, appliedDiscounts } = computeGroupCouponDiscount(appliedCoupons, groupLines, groupTotal, cartSubtotal, firstItem.storeId);
     // Mirrors createOrderForGroup — without this the online-payment path wrote
     // the discount onto the order but never incremented usage.currentUsage or
@@ -1398,8 +1407,8 @@ export async function verifyAndPlaceRazorpayOrderAction(input) {
             .map(({ item, product }) => ({ item, product })),
     });
     // S-SBUNI-RULES 2026-05-13 — sync preflight via rule registry.
-    // Bundle items bypass the cart flow so skip the prize-pool cap.
-    const preflightPairs = productChecks.filter((p) => p.product !== null && p.product !== undefined && !p.item.bundleProductIds?.length);
+    // Multi-member lines skip the prize-pool cap, same reasoning as the COD path.
+    const preflightPairs = productChecks.filter((p) => p.product !== null && p.product !== undefined && !isMultiMemberLine(p.item));
     // This whole action is the Razorpay path — paymentMethod is always "online".
     runSyncPreflight(preflightPairs, "online");
     // SB-UNI-O 2026-05-15 — Live-item jurisdiction guard.
@@ -1469,7 +1478,7 @@ export async function verifyAndPlaceRazorpayOrderAction(input) {
         const expectedAddonFees = expectedShippingGroups.reduce((sum, g) => {
             const storeId = g.items[0].item.storeId;
             const addons = cart.storeAddons?.[storeId] ?? {};
-            const groupSubtotal = g.items.reduce((gs, { item, product }) => gs + unitPriceFor(item, product) * item.quantity, 0);
+            const groupSubtotal = g.items.reduce((gs, { item, product }) => gs + lineTotalFor(item, product), 0);
             return (sum +
                 computeWhatsAppNotifyFee(addons.whatsappNotifyAddon ?? false, commissionRates) +
                 computeGiftWrapFee(addons.giftWrapAddon ?? false, commissionRates) +
@@ -1501,12 +1510,12 @@ export async function verifyAndPlaceRazorpayOrderAction(input) {
     let total = 0;
     const emailsToSend = [];
     const cartSubtotal = orderGroups.reduce((s, { items: g }) => s +
-        g.reduce((gs, { item, product }) => gs + unitPriceFor(item, product) * item.quantity, 0), 0);
+        g.reduce((gs, { item, product }) => gs + lineTotalFor(item, product), 0), 0);
     const couponUsageAccumulator = new Map();
     // Same single capped commission + pro-rata split as the COD/UPI path.
     const platformFeeByStore = allocateCheckoutFees(orderGroups.map(({ items: g }) => [
         g[0].item.storeId,
-        g.reduce((sum, { item, product }) => sum + unitPriceFor(item, product) * item.quantity, 0),
+        g.reduce((sum, { item, product }) => sum + lineTotalFor(item, product), 0),
     ]), computeCheckoutFees(cartSubtotal, siteSettings?.commissions ?? CHECKOUT_DEFAULT_COMMISSIONS));
     for (const { items: group, orderType } of orderGroups) {
         total += await createRazorpayGroupOrder(group, orderType, {

package/dist/_internal/server/features/checkout/bundle-expansion.d.ts

@@ -22,19 +22,17 @@
  */
 import type { CartItemDocument } from "../../../../features/cart/schemas";
 import type { ProductDocument } from "../../../../features/products/schemas/firestore";
+export { getCartLineMembers, getCartItemMemberIds, isMultiMemberLine, type CartLineMemberRef, } from "../../../shared/checkout/line-members";
 export interface BundleExpansion {
     /** Unique product ids referenced by any cart item (regular or bundle member). */
     productIds: string[];
     /**
-     * Sum of requested quantities per product id. Bundle members get
-     * `item.quantity` per occurrence (so 2x of a bundle with member X
-     * decrements X by 2, not 1).
+     * Sum of requested quantities per product id, weighted by BOTH the number of
+     * copies of the line and each member's per-copy quantity — so 2 copies of a
+     * selection containing 3× member X decrement X by 6.
      */
     decrements: Map<string, number>;
 }
-/** Resolve the member-product ids for a cart item. Bundle items expand to
- *  `bundleProductIds[]`; regular items collapse to `[productId]`. */
-export declare function getCartItemMemberIds(item: CartItemDocument): string[];
 /** Build the unique-product-id + per-product decrement map for a cart. */
 export declare function getExpandedDecrements(cartItems: CartItemDocument[]): BundleExpansion;
 export interface StockShortfall {

package/dist/_internal/server/features/checkout/bundle-expansion.js

@@ -21,21 +21,21 @@
  * the first's decrement before re-running its own validation.
  */
 import { ProductStatusValues } from "../../../../features/products/schemas/firestore";
-/** Resolve the member-product ids for a cart item. Bundle items expand to
- *  `bundleProductIds[]`; regular items collapse to `[productId]`. */
-export function getCartItemMemberIds(item) {
-    if (item.bundleProductIds && item.bundleProductIds.length > 0) {
-        return item.bundleProductIds;
-    }
-    return [item.productId];
-}
+import { getCartLineMembers } from "../../../shared/checkout/line-members";
+// Re-exported here so the many existing importers of this module keep working;
+// the definitions live in shared/ because `rules/_registry.ts` and
+// `order-math.ts` need them too and cannot import from server/.
+export { getCartLineMembers, getCartItemMemberIds, isMultiMemberLine, } from "../../../shared/checkout/line-members";
 /** Build the unique-product-id + per-product decrement map for a cart. */
 export function getExpandedDecrements(cartItems) {
     const decrements = new Map();
     for (const item of cartItems) {
-        const memberIds = getCartItemMemberIds(item);
-        for (const pid of memberIds) {
-            decrements.set(pid, (decrements.get(pid) ?? 0) + item.quantity);
+        for (const member of getCartLineMembers(item)) {
+            // item.quantity = copies of the line, member.quantity = units per copy.
+            // Multiplying is the whole point: this used to add `item.quantity` alone,
+            // which silently assumed exactly one of each member.
+            const needed = item.quantity * member.quantity;
+            decrements.set(member.productId, (decrements.get(member.productId) ?? 0) + needed);
         }
     }
     return {
@@ -55,15 +55,17 @@ export function getExpandedDecrements(cartItems) {
  * that product, not just this item's slice.
  */
 export function validateCartItemStock(item, productById, decrements) {
-    const memberIds = getCartItemMemberIds(item);
-    for (const pid of memberIds) {
-        const product = productById.get(pid);
+    for (const member of getCartLineMembers(item)) {
+        const product = productById.get(member.productId);
         if (!product || product.status !== ProductStatusValues.PUBLISHED) {
-            return { productId: pid, availableQty: product?.availableQuantity ?? 0 };
+            return { productId: member.productId, availableQty: product?.availableQuantity ?? 0 };
         }
-        const totalNeeded = decrements.get(pid) ?? item.quantity;
+        // The fallback must be member-weighted too. Left as a bare `item.quantity`
+        // it would validate a line needing 3× of a member against demand for 1
+        // whenever the cumulative map didn't happen to carry that product.
+        const totalNeeded = decrements.get(member.productId) ?? item.quantity * member.quantity;
         if (product.availableQuantity < totalNeeded) {
-            return { productId: pid, availableQty: product.availableQuantity };
+            return { productId: member.productId, availableQty: product.availableQuantity };
         }
     }
     return null;

package/dist/_internal/server/features/checkout/stock-restore.js

@@ -1,6 +1,7 @@
 import { ORDER_COLLECTION } from "../../../../features/orders/schemas/firestore";
 import { PRODUCT_COLLECTION } from "../../../../features/products/schemas/firestore";
 import { getListingRule } from "../../../shared/checkout/rules";
+import { getOrderItemMemberRefs } from "../../../shared/checkout/line-members";
 /**
  * Per-product quantity to restore for one order — the inverse of
  * `getExpandedDecrements` (bundle-expansion.ts), but reads from
@@ -15,11 +16,11 @@ function getOrderRestoreMap(order) {
         const remainingQty = item.quantity - (item.cancelledQuantity ?? 0);
         if (remainingQty <= 0)
             continue;
-        const memberIds = item.bundleProductIds && item.bundleProductIds.length > 0
-            ? item.bundleProductIds
-            : [item.productId];
-        for (const pid of memberIds) {
-            map.set(pid, (map.get(pid) ?? 0) + remainingQty);
+        // Must mirror `getExpandedDecrements` exactly, including the per-member
+        // weighting — restoring fewer units than were taken silently leaks stock.
+        for (const member of getOrderItemMemberRefs(item)) {
+            const pid = member.productId;
+            map.set(pid, (map.get(pid) ?? 0) + remainingQty * member.quantity);
         }
     }
     return map;

package/dist/_internal/server/features/products/group-members.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Public projection for a product-group member.
+ *
+ * `GET /api/products/group/[groupId]` previously returned
+ * `sanitizeProductsForPublic(items)`, which is a DELETE-LIST of four
+ * seller-identity keys — every other field of `ProductDocument` went to the
+ * browser, including fields nobody had thought about. Per § "Public Data
+ * Projections", a public payload is built by naming what goes out, never by
+ * spreading a document and removing keys: a denial keyed on today's field list
+ * is structurally blind to the field added tomorrow.
+ *
+ * The member picker needs more than the old response carried (stock, store,
+ * sold state, gstRate), so widening the payload was required either way —
+ * which made this the moment to make it an allow-list rather than a wider
+ * deny-list.
+ */
+import type { ProductDocument } from "../../../../features/products/schemas/firestore";
+import type { ListingType } from "../../../../features/products/types/index";
+/**
+ * Every field the group picker and the group table render. If a field is not
+ * here it does not reach the browser.
+ *
+ * Deliberately absent, with reasons:
+ *  - `sellerId` / `ownerId` / `sellerName` / `sellerEmail` — seller identity;
+ *    public clients see store-scoped identity only.
+ *  - `costPrice`, `profitMargin`, `supplier*`, `adminNotes` — seller-private
+ *    commercial data.
+ *  - `stockQuantity` — the internal figure; `availableQuantity` is the one the
+ *    buyer may act on.
+ */
+export interface PublicGroupMember {
+    id: string;
+    slug?: string;
+    title: string;
+    price: number;
+    currency?: string;
+    /** First image only — the picker renders a thumbnail, never a gallery. */
+    image?: string;
+    condition?: string;
+    listingType: ListingType;
+    isGroupParent?: boolean;
+    groupTitle?: string;
+    /** Drives the stepper's `max`. */
+    availableQuantity: number;
+    storeId: string;
+    storeName?: string;
+    status: string;
+    isSold?: boolean;
+    /** Needed so the picker can show a tax-inclusive hint and the cart line can
+     *  snapshot it for per-member GST proration at checkout. */
+    gstRate?: 0 | 5 | 12 | 18 | 28;
+    hsnCode?: string;
+}
+export declare function toPublicGroupMember(doc: ProductDocument): PublicGroupMember;
+export declare function toPublicGroupMembers(docs: readonly ProductDocument[]): PublicGroupMember[];

package/dist/_internal/server/features/products/group-members.js

@@ -0,0 +1,41 @@
+/**
+ * Public projection for a product-group member.
+ *
+ * `GET /api/products/group/[groupId]` previously returned
+ * `sanitizeProductsForPublic(items)`, which is a DELETE-LIST of four
+ * seller-identity keys — every other field of `ProductDocument` went to the
+ * browser, including fields nobody had thought about. Per § "Public Data
+ * Projections", a public payload is built by naming what goes out, never by
+ * spreading a document and removing keys: a denial keyed on today's field list
+ * is structurally blind to the field added tomorrow.
+ *
+ * The member picker needs more than the old response carried (stock, store,
+ * sold state, gstRate), so widening the payload was required either way —
+ * which made this the moment to make it an allow-list rather than a wider
+ * deny-list.
+ */
+import { normalizeListingType } from "../../../../features/products/utils/listing-type";
+export function toPublicGroupMember(doc) {
+    return {
+        id: doc.id,
+        slug: doc.slug,
+        title: doc.title,
+        price: doc.price,
+        currency: doc.currency,
+        image: doc.images?.[0] ?? doc.mainImage,
+        condition: doc.condition,
+        listingType: normalizeListingType(doc),
+        isGroupParent: doc.isGroupParent,
+        groupTitle: doc.groupTitle,
+        availableQuantity: doc.availableQuantity ?? 0,
+        storeId: doc.storeId,
+        storeName: doc.storeName,
+        status: doc.status,
+        isSold: doc.isSold,
+        gstRate: doc.gstRate,
+        hsnCode: doc.hsnCode,
+    };
+}
+export function toPublicGroupMembers(docs) {
+    return docs.map(toPublicGroupMember);
+}

package/dist/_internal/shared/actions/action-registry.js

@@ -2412,6 +2412,47 @@ export const ACTIONS = {
             description: "Navigate back from the cart to the product catalogue.",
             kind: "ghost",
         },
+        "add-group-to-cart": {
+            iconKey: "cart",
+            id: "cart.add-group-to-cart",
+            label: "Add selected to cart",
+            ariaLabel: "Add the selected group items to the cart as one line",
+            description: "Add a buyer-assembled selection of group members to the cart as a SINGLE line, rather than one line per product.",
+            kind: "primary",
+        },
+        "add-bundle-to-cart": {
+            iconKey: "cart",
+            id: "cart.add-bundle-to-cart",
+            label: "Add to cart",
+            ariaLabel: "Add this bundle to the cart",
+            description: "Add a whole bundle to the cart. Bundles are all-or-nothing — the quantity is the number of COPIES of the bundle.",
+            kind: "primary",
+        },
+        "remove-group-member": {
+            iconKey: "delete",
+            id: "cart.remove-group-member",
+            label: "Remove",
+            ariaLabel: "Remove this item from the group line",
+            description: "Drop one member out of a grouped cart line. Ghost rather than danger on purpose: it reuses the cart's existing undo affordance, and Rule #7.4's mandatory-confirmation requirement applies to destructive actions.",
+            kind: "ghost",
+        },
+        // No iconKey — these two exist only to keep the stepper's accessible names
+        // in the registry rather than hard-coded in the primitive. The glyphs are
+        // the literal "+" / "−" characters.
+        "increase-quantity": {
+            id: "cart.increase-quantity",
+            label: "+",
+            ariaLabel: "Increase quantity",
+            description: "Default accessible name for QuantityStepper's increment control.",
+            kind: "ghost",
+        },
+        "decrease-quantity": {
+            id: "cart.decrease-quantity",
+            label: "−",
+            ariaLabel: "Decrease quantity",
+            description: "Default accessible name for QuantityStepper's decrement control.",
+            kind: "ghost",
+        },
     },
     CHECKOUT: {
         "place-order": {

package/dist/_internal/shared/checkout/line-members.d.ts

@@ -0,0 +1,60 @@
+/**
+ * "What products does this cart line actually consume?" — the one answer.
+ *
+ * Lives in `shared/` rather than `server/features/checkout/` because three
+ * different layers need it and two of them are not server code:
+ *   - `order-math.ts`         (pricing + tax, shared)
+ *   - `rules/_registry.ts`    (preflight skip, shared)
+ *   - `bundle-expansion.ts`   (stock fan-out, server)
+ *   - `stock-restore.ts`      (restore fan-out, server)
+ *
+ * Pure functions, no Firestore, no framework imports.
+ */
+import type { CartItemDocument } from "../../../features/cart/schemas/firestore";
+/** One member of a cart line, with the units required per COPY of that line. */
+export interface CartLineMemberRef {
+    productId: string;
+    quantity: number;
+}
+/**
+ * Resolve a line's members. Three sources, in priority order — never read
+ * `bundleProductIds` directly at a call site:
+ *
+ *  1. `groupMembers` — authoritative, and the only shape that can express
+ *     per-member quantities.
+ *  2. `bundleProductIds` — legacy bundle lines written before `groupMembers`
+ *     existed, resolved at quantity 1 each. This fallback is what makes carts
+ *     that were already in flight behave byte-identically, with no migration.
+ *  3. the line's own `productId` — an ordinary single-product line.
+ *
+ * Keeping this a derivation rather than storing a second array is deliberate: a
+ * hand-maintained mirror drifts the first time one write path forgets it
+ * (Recurrent Root Cause #42).
+ */
+export declare function getCartLineMembers(item: CartItemDocument): CartLineMemberRef[];
+/**
+ * True when the line stands for several products rather than one.
+ *
+ * Replaces the scattered `item.bundleProductIds?.length` tests, which each
+ * meant "is this a bundle" and would all have silently answered "no" for a
+ * `groupMembers`-backed line.
+ */
+export declare function isMultiMemberLine(item: CartItemDocument): boolean;
+/** Just the product ids — see `getCartLineMembers` for the resolution order. */
+export declare function getCartItemMemberIds(item: CartItemDocument): string[];
+/** The order-side shape this module needs. Structural on purpose — it matches
+ *  `OrderDocumentItem` without dragging the orders schema into shared checkout. */
+export interface OrderItemMemberSource {
+    productId: string;
+    bundleProductIds?: string[];
+}
+/**
+ * The order-side twin of `getCartLineMembers`, used by stock restore.
+ *
+ * A LEGACY order row is collapsed: one row standing for a whole bundle, with
+ * its members listed in `bundleProductIds` at one unit each. Rows written after
+ * grouped lines were expanded carry no `bundleProductIds` at all — each row is
+ * already exactly one product — so they fall through to the single-member
+ * branch and need no special case.
+ */
+export declare function getOrderItemMemberRefs(item: OrderItemMemberSource): CartLineMemberRef[];

package/dist/_internal/shared/checkout/line-members.js

@@ -0,0 +1,68 @@
+/**
+ * "What products does this cart line actually consume?" — the one answer.
+ *
+ * Lives in `shared/` rather than `server/features/checkout/` because three
+ * different layers need it and two of them are not server code:
+ *   - `order-math.ts`         (pricing + tax, shared)
+ *   - `rules/_registry.ts`    (preflight skip, shared)
+ *   - `bundle-expansion.ts`   (stock fan-out, server)
+ *   - `stock-restore.ts`      (restore fan-out, server)
+ *
+ * Pure functions, no Firestore, no framework imports.
+ */
+/**
+ * Resolve a line's members. Three sources, in priority order — never read
+ * `bundleProductIds` directly at a call site:
+ *
+ *  1. `groupMembers` — authoritative, and the only shape that can express
+ *     per-member quantities.
+ *  2. `bundleProductIds` — legacy bundle lines written before `groupMembers`
+ *     existed, resolved at quantity 1 each. This fallback is what makes carts
+ *     that were already in flight behave byte-identically, with no migration.
+ *  3. the line's own `productId` — an ordinary single-product line.
+ *
+ * Keeping this a derivation rather than storing a second array is deliberate: a
+ * hand-maintained mirror drifts the first time one write path forgets it
+ * (Recurrent Root Cause #42).
+ */
+export function getCartLineMembers(item) {
+    if (item.groupMembers?.length) {
+        return item.groupMembers.map((m) => ({
+            productId: m.productId,
+            quantity: m.quantity,
+        }));
+    }
+    if (item.bundleProductIds?.length) {
+        return item.bundleProductIds.map((productId) => ({ productId, quantity: 1 }));
+    }
+    return [{ productId: item.productId, quantity: 1 }];
+}
+/**
+ * True when the line stands for several products rather than one.
+ *
+ * Replaces the scattered `item.bundleProductIds?.length` tests, which each
+ * meant "is this a bundle" and would all have silently answered "no" for a
+ * `groupMembers`-backed line.
+ */
+export function isMultiMemberLine(item) {
+    return Boolean(item.groupMembers?.length || item.bundleProductIds?.length);
+}
+/** Just the product ids — see `getCartLineMembers` for the resolution order. */
+export function getCartItemMemberIds(item) {
+    return getCartLineMembers(item).map((m) => m.productId);
+}
+/**
+ * The order-side twin of `getCartLineMembers`, used by stock restore.
+ *
+ * A LEGACY order row is collapsed: one row standing for a whole bundle, with
+ * its members listed in `bundleProductIds` at one unit each. Rows written after
+ * grouped lines were expanded carry no `bundleProductIds` at all — each row is
+ * already exactly one product — so they fall through to the single-member
+ * branch and need no special case.
+ */
+export function getOrderItemMemberRefs(item) {
+    if (item.bundleProductIds?.length) {
+        return item.bundleProductIds.map((productId) => ({ productId, quantity: 1 }));
+    }
+    return [{ productId: item.productId, quantity: 1 }];
+}

package/dist/_internal/shared/checkout/order-math.d.ts

@@ -7,9 +7,9 @@
 import type { CartItemDocument } from "../../../features/cart/schemas/firestore";
 import type { ProductDocument } from "../../../features/products/schemas/firestore";
 /**
- * The single source of truth for "what do we charge for this line".
+ * The single source of truth for "what do we charge for ONE COPY of this line".
  *
- * Three cases, in priority order:
+ * Four cases, in priority order:
  *
  *  1. **A locked price** — an accepted offer or a won auction. `lockedPrice` is
  *     the negotiated/won amount and it OVERRIDES the current listing price, which
@@ -17,15 +17,33 @@ import type { ProductDocument } from "../../../features/products/schemas/firesto
  *     copies of this function looked at `lockedPrice`, so an accepted offer was
  *     billed at the seller's listed price while the cart UI displayed the agreed
  *     one (`item.lockedPrice ?? item.price`) — the buyer saw ₹X and paid ₹Y.
- *  2. **A bundle line** (SB-UNI-5 2026-05-13) — `item.price` is the bundle price
- *     locked at add-time.
- *  3. **Everything else** — the live Firestore price, so a stale cart-cached
+ *  2. **A multi-member line** — the sum of its members' own snapshotted prices,
+ *     weighted by each member's per-copy quantity. A `"group"` line pins
+ *     `item.quantity` to 1, so this is both the unit price and the line total;
+ *     see the invariant on `CartLineMember`.
+ *  3. **A legacy bundle line** (SB-UNI-5 2026-05-13) — written before
+ *     `groupMembers` existed. `item.price` is the bundle price locked at
+ *     add-time.
+ *  4. **Everything else** — the live Firestore price, so a stale cart-cached
  *     price is never charged on a COD/UPI order.
  *
  * `product` may be null for a locked line whose listing has since been archived;
  * the locked price is still owed, so that case must not dereference `product`.
+ *
+ * 🛑 Do not hand-roll this rule at a call site. It has been re-derived by hand
+ * six times, and the two copies that lived in the consumer repo
+ * (`src/app/api/payment/create-order/route.ts`) each reproduced the bundle
+ * branch while silently omitting case 1 — so Razorpay captured the LIST price
+ * for an accepted offer while the cart displayed the negotiated one. Call
+ * `lineTotalFor` and let this function stay the only definition.
  */
 export declare function unitPriceFor(item: CartItemDocument, product: ProductDocument | null): number;
+/**
+ * What this line contributes to a subtotal: one copy's price × the number of
+ * copies. THE call site should use this rather than multiplying `unitPriceFor`
+ * itself — that multiplication is where the six hand-rolled copies diverged.
+ */
+export declare function lineTotalFor(item: CartItemDocument, product: ProductDocument | null): number;
 /**
  * P-6 — pre-order groups charge each product's own `preOrderDepositPercent`
  * (falling back to the generic COD deposit % when a product doesn't have one