@mohasinac/appkit 4.71.0 → 4.72.0

package/dist/_internal/shared/features/shipping/offer.js

@@ -0,0 +1,440 @@
+/**
+ * THE SELLER'S SHIPPING OFFER, THE BUYER'S CHOICE, AND THE SERVER'S AUTHORITY.
+ *
+ * Pure and synchronous — no I/O, no Firestore, no provider. One module decides
+ * what a seller offers, what the buyer may pick, and what the buyer is charged,
+ * so the picker, the preview, the capture and the order record cannot disagree
+ * (Root Cause #75: a money rule reachable by copy-paste WILL be copied, and the
+ * copy never learns about the branch added later).
+ *
+ * ## Owner, 2026-11-08 — the spec this file implements, verbatim
+ *
+ * *"A seller agrees from their dashboard for the shipping option. If they
+ * select custom — i.e. their own — then they must set a per-order fee. But if
+ * they are okay with our shipping providers' quotes then they must accept that
+ * as well. Both can be enabled. When the buyer shops, at checkout they can
+ * select the custom shipping (say ₹200 set by the seller) or check the quote
+ * from the shipment integrations; if they find the other cheap they can choose
+ * whatever they wish. But if they have selected that, then it is up to the
+ * seller to fulfil as is — they cannot use the platform to ship for the other,
+ * as we have already taken money from the customer. If however they need to
+ * override it, they can refund the excess if any; and in case they needed to
+ * pay more for their custom shipping than what the buyer paid, they have to
+ * swallow that money as a loss."*
+ *
+ * ## 🛑 THE DEFECT THIS FILE EXISTS TO CLOSE
+ *
+ * Measured live 2026-11-08 on a ₹149 item at `checkout/actions.ts:1595`:
+ *
+ * ```
+ * shippingFee = roundShippingUp(selectedShippingQuote.chargedRate)
+ * ```
+ *
+ * honest request → charged total **₹172.69**
+ * forged `{ chargedRate: 1 }` → charged total **₹222.69**
+ *
+ * A number the CLIENT posted reached the charged total. The server's own
+ * `resolveShippingCost` result was computed and then discarded. The old comment
+ * argued the trust was "bounded" because `roundShippingUp` re-rounds it — but
+ * re-rounding a forged number only guarantees the forgery lands on a ₹50 step.
+ * ₹1 rounds to ₹50 and ₹10,000 rounds to ₹10,000; the bound is the attacker's
+ * choice, not ours. Undercutting was not exploitable only because no seeded
+ * store had `shippingPricing` configured, so every resolved fee was ₹0 — i.e.
+ * the protection was a data accident, due to expire the moment a vendor set a
+ * real rate.
+ *
+ * ## 🛑 Why the fix is NOT "forbid a client-supplied shipping value"
+ *
+ * This is the load-bearing architectural point, and the obvious fix is wrong.
+ *
+ * The buyer **legitimately chooses** between the seller's custom rate and a
+ * carrier quote — that is the owner's spec, not a loophole. So a client must be
+ * able to express *which* option it picked. What it must never be able to
+ * express is *what that option costs*.
+ *
+ * Therefore:
+ *
+ *   · a posted **amount** (`chargedRate`, `rawRate`) is ignored entirely;
+ *   · a posted **option identifier** is validated against the options this
+ *     seller actually offers, re-priced from stored config plus a
+ *     server-obtained carrier quote, and the SERVER's number is charged;
+ *   · an identifier that is not on that list is a **refusal**, never a silent
+ *     fallback. Falling back would charge the buyer for a method they did not
+ *     choose, which is the same class of defect pointing the other way.
+ *
+ * ## 🛑 Capability-driven, never type-driven
+ *
+ * Whether an order has shipping at all is `supportsShipping` on the capability
+ * registry, resolved by the caller through `cartRequiresShipping`. This module
+ * takes that answer as a boolean input and never looks at a listing type. A
+ * digital-code cart therefore acquires no fee and no obligation — not because
+ * this file knows what a digital code is, but because its caller said no line
+ * in the cart supports shipping.
+ */
+import { roundShippingUp } from "../../shipping/quote.js";
+import { DEFAULT_STORE_SHIPPING_POLICY, toStoreShippingPolicy, } from "./mode.js";
+/**
+ * What a store that has configured nothing offers.
+ *
+ * 🛑 Custom at ₹0, NOT platform quotes — the conservative choice rather than
+ * the generous-looking one, and identical in effect to
+ * `DEFAULT_STORE_SHIPPING_POLICY`'s `free`. Defaulting to platform quotes would
+ * hold a buyer's money against a carrier booking the seller has never agreed
+ * to make, and the fulfilment obligation would bind a seller who never saw the
+ * setting. A store that has not opened its shipping page keeps doing exactly
+ * what it does today: charges nothing and ships manually.
+ */
+export const DEFAULT_SELLER_SHIPPING_OFFER = {
+    platformQuotesAccepted: false,
+    customEnabled: true,
+    customFeePerOrder: 0,
+    customFreeAbove: null,
+    customLabel: null,
+};
+function positiveOrNull(value) {
+    return typeof value === "number" && Number.isFinite(value) && value > 0 ? value : null;
+}
+function nonNegativeOrNull(value) {
+    return typeof value === "number" && Number.isFinite(value) && value >= 0 ? value : null;
+}
+/**
+ * The offer implied by a legacy single-mode policy.
+ *
+ * 🛑 This is what stops this being a THIRD shipping-config system. Every store
+ * on the platform today has at most a `StoreShippingPolicy`, and the mapping is
+ * lossless in the direction that matters:
+ *
+ *   `free`             → custom at ₹0        (seller absorbs, ships manually)
+ *   `flat` amount A    → custom at ₹A        (the seller's own price)
+ *   `estimate`         → platform quotes     (our carrier account books it)
+ *
+ * So a seller who set ₹100 on the old surface keeps charging ₹100 and gains the
+ * obligation that already described what they were doing, rather than silently
+ * dropping to free or silently acquiring a carrier integration.
+ */
+export function offerFromPolicy(policy) {
+    const freeAbove = positiveOrNull(policy.freeAbove);
+    switch (policy.mode.kind) {
+        case "estimate":
+            return {
+                platformQuotesAccepted: true,
+                customEnabled: false,
+                customFeePerOrder: null,
+                customFreeAbove: freeAbove,
+                customLabel: null,
+            };
+        case "flat":
+            return {
+                platformQuotesAccepted: false,
+                customEnabled: true,
+                customFeePerOrder: policy.mode.amount,
+                customFreeAbove: freeAbove,
+                customLabel: null,
+            };
+        case "free":
+            return { ...DEFAULT_SELLER_SHIPPING_OFFER, customFreeAbove: freeAbove };
+        default: {
+            // Exhaustive: a fourth mode must not compile to a silent free shipment.
+            const unreachable = policy.mode;
+            return unreachable;
+        }
+    }
+}
+/**
+ * Narrow a stored `shippingPricing` value into the seller's offer.
+ *
+ * Reads the explicit `offer` when one has been saved, and derives it from the
+ * legacy mode otherwise. An offer that stores nothing usable — neither axis
+ * true — falls back to the derived policy rather than to "offers nothing",
+ * because "this store offers no shipping method" must come from a seller
+ * deliberately saying so (which `validateSellerShippingOffer` refuses anyway),
+ * never from a half-written document.
+ */
+export function toSellerShippingOffer(raw) {
+    if (!raw || typeof raw !== "object")
+        return { ...DEFAULT_SELLER_SHIPPING_OFFER };
+    const wire = raw;
+    const derived = offerFromPolicy(wire.mode || wire.freeAbove !== undefined
+        ? toStoreShippingPolicy(wire)
+        : DEFAULT_STORE_SHIPPING_POLICY);
+    const offer = wire.offer;
+    if (!offer || typeof offer !== "object")
+        return derived;
+    const platformQuotesAccepted = offer.platformQuotesAccepted === true;
+    const customEnabled = offer.customEnabled === true;
+    if (!platformQuotesAccepted && !customEnabled)
+        return derived;
+    return {
+        platformQuotesAccepted,
+        customEnabled,
+        /*
+         * 🛑 `nonNegativeOrNull`, so a stored ₹0 survives as ₹0 and anything
+         * unusable becomes `null` — never 0. A `customEnabled` offer that reaches
+         * `null` here cannot produce a custom option at all (see
+         * `buildShippingOptions`), which is the visible failure. Coercing it to
+         * free would be the invisible one, and would charge the buyer nothing for
+         * a parcel the seller still has to post.
+         */
+        customFeePerOrder: customEnabled ? nonNegativeOrNull(offer.customFeePerOrder) : null,
+        customFreeAbove: positiveOrNull(offer.customFreeAbove),
+        customLabel: typeof offer.customLabel === "string" && offer.customLabel.trim().length > 0
+            ? offer.customLabel.trim().slice(0, 120)
+            : null,
+    };
+}
+/**
+ * May this offer be saved?
+ *
+ * 🛑 REFUSES rather than defaulting, and that is the owner's spec read
+ * literally: *"if they select custom … then they MUST set a per-order fee"*.
+ * A missing fee defaulted to ₹0 is a seller who believes they are charging for
+ * postage and is not — they discover it when the payout arrives, by which time
+ * the parcels have been posted and the money cannot be recovered from the
+ * buyer. Refusing at save time costs one form error.
+ *
+ * 🛑 It also refuses an offer with NEITHER axis. A seller offering no shipping
+ * method cannot fulfil a physical order, and the honest place to say so is the
+ * settings form — not a buyer's checkout, where the only available answers are
+ * "charge nothing" (we ship free) or "block the purchase" (the seller loses the
+ * sale without being told why).
+ */
+export function validateSellerShippingOffer(input) {
+    const platformQuotesAccepted = input.platformQuotesAccepted === true;
+    const customEnabled = input.customEnabled === true;
+    if (!platformQuotesAccepted && !customEnabled) {
+        return {
+            ok: false,
+            reason: "no-method",
+            message: "Enable at least one shipping method — our carrier quotes, your own rate, or both.",
+        };
+    }
+    let customFeePerOrder = null;
+    if (customEnabled) {
+        const fee = input.customFeePerOrder;
+        if (fee === null || fee === undefined) {
+            return {
+                ok: false,
+                reason: "custom-without-fee",
+                message: "Set your per-order shipping fee. Enter 0 if you ship free — leaving it blank is not the same thing.",
+            };
+        }
+        if (typeof fee !== "number" || !Number.isFinite(fee) || fee < 0) {
+            return {
+                ok: false,
+                reason: "fee-not-a-price",
+                message: "Your per-order shipping fee must be ₹0 or more.",
+            };
+        }
+        customFeePerOrder = roundToPaise(fee);
+    }
+    const threshold = input.customFreeAbove;
+    if (threshold !== null && threshold !== undefined) {
+        if (typeof threshold !== "number" || !Number.isFinite(threshold) || threshold <= 0) {
+            return {
+                ok: false,
+                reason: "threshold-not-a-price",
+                message: "A free-shipping threshold must be more than ₹0. Leave it blank to disable it.",
+            };
+        }
+    }
+    return {
+        ok: true,
+        offer: {
+            platformQuotesAccepted,
+            customEnabled,
+            customFeePerOrder,
+            customFreeAbove: threshold == null ? null : roundToPaise(threshold),
+            customLabel: typeof input.customLabel === "string" && input.customLabel.trim().length > 0
+                ? input.customLabel.trim().slice(0, 120)
+                : null,
+        },
+    };
+}
+// ── B: THE OPTIONS THE BUYER MAY PICK ────────────────────────────────────────
+/** The id the buyer posts back for the seller's own rate. */
+export const CUSTOM_SHIPPING_OPTION_ID = "custom";
+/**
+ * The id for one carrier option.
+ *
+ * Namespaced so a carrier can never return the literal `"custom"` and collide
+ * with the seller's own option — which would let a tampered pick land on the
+ * wrong side of the fulfilment obligation.
+ */
+export function platformShippingOptionId(courierId) {
+    return `platform:${courierId}`;
+}
+/**
+ * Everything this seller is willing to ship by, priced.
+ *
+ * 🛑 The custom fee is NOT put through `roundShippingUp`, and the platform
+ * options already are. That asymmetry is deliberate and is the point of the
+ * ₹50 step: it exists to make a volatile machine-read CARRIER RATE look like a
+ * stable price. A seller's own ₹60 is already a price — a human typed it and
+ * published it — so rounding it to ₹100 would charge the buyer ₹40 the seller
+ * never asked for and show a figure that appears nowhere in the seller's
+ * settings. `toQuoteOptions` applies the step to carrier rates at the one place
+ * they enter the system; nothing else needs it.
+ *
+ * 🛑 A `customEnabled` offer with a `null` fee produces NO custom option rather
+ * than a free one. See `toSellerShippingOffer` — an unfinished configuration
+ * must fail visibly, not post parcels for free.
+ *
+ * Cheapest first, because the buyer is choosing and the owner's spec says
+ * explicitly that they may take whichever is cheaper.
+ */
+export function buildShippingOptions(input) {
+    const { offer, goodsValue, carrierOptions = [] } = input;
+    const options = [];
+    if (offer.customEnabled && offer.customFeePerOrder != null) {
+        const freeByThreshold = offer.customFreeAbove != null && goodsValue >= offer.customFreeAbove;
+        options.push({
+            optionId: CUSTOM_SHIPPING_OPTION_ID,
+            kind: "custom",
+            label: offer.customLabel ?? "Seller's own shipping",
+            amount: freeByThreshold ? 0 : roundToPaise(offer.customFeePerOrder),
+            reason: freeByThreshold ? "custom-free-above" : "custom",
+        });
+    }
+    if (offer.platformQuotesAccepted) {
+        for (const courier of carrierOptions) {
+            /*
+             * `freeAbove` applies to the seller's OWN rate only. A carrier label
+             * costs real money whoever ordered it, and waiving it would mean the
+             * platform buying postage out of its own pocket on a threshold the
+             * seller set. The seller's way to offer free carrier shipping is to
+             * price their custom option at ₹0.
+             */
+            options.push({
+                optionId: platformShippingOptionId(courier.courierId),
+                kind: "platform",
+                label: courier.courierName,
+                amount: roundShippingUp(courier.chargedRate),
+                reason: "carrier",
+                estimatedDays: courier.estimatedDays,
+                courierId: courier.courierId,
+                courierName: courier.courierName,
+            });
+        }
+    }
+    return options.sort((a, b) => a.amount - b.amount || (a.estimatedDays ?? 0) - (b.estimatedDays ?? 0));
+}
+/**
+ * Re-resolve the buyer's chosen OPTION against the seller's stored offer and a
+ * server-obtained carrier quote, and return the SERVER's price for it.
+ *
+ * This is the single function that answers "what is this order charged for
+ * shipping, and what did the seller therefore agree to do".
+ */
+export function resolveShippingSelection(input) {
+    const { shippingRequired, offer, goodsValue, carrierOptions, requestedOptionId } = input;
+    /*
+     * 🛑 FIRST, before anything else. A cart with no shippable line must acquire
+     * no fee and no obligation even if a client posts an option id — a stale
+     * picker on a digital-code checkout must not be able to attach a parcel
+     * obligation to a code delivered by email.
+     */
+    if (!shippingRequired)
+        return { kind: "not-required" };
+    const options = buildShippingOptions({ offer, goodsValue, carrierOptions });
+    if (!requestedOptionId)
+        return { kind: "unselected" };
+    const chosen = options.find((o) => o.optionId === requestedOptionId);
+    if (!chosen) {
+        /*
+         * Two different failures, two different messages, because the buyer can act
+         * on one of them and not the other. "We could not get carrier rates" means
+         * pick the other option or retry; "that option is not available" means the
+         * page is stale and should be reloaded.
+         */
+        if (options.length === 0) {
+            return {
+                kind: "refused",
+                reason: "no-method-available",
+                message: "This seller has no shipping method available for your address right now. Please try again shortly.",
+            };
+        }
+        return {
+            kind: "refused",
+            reason: "option-not-offered",
+            message: "The shipping option you selected is no longer offered for this order. Please reload checkout and choose again.",
+        };
+    }
+    return {
+        kind: "resolved",
+        option: chosen,
+        obligation: {
+            kind: chosen.kind,
+            optionId: chosen.optionId,
+            chargedAmount: chosen.amount,
+            label: chosen.label,
+            mustSelfFulfil: chosen.kind === "custom",
+            ...(chosen.courierId ? { courierId: chosen.courierId } : {}),
+            ...(chosen.courierName ? { courierName: chosen.courierName } : {}),
+        },
+    };
+}
+/**
+ * The obligation an offer implies when the buyer made NO choice.
+ *
+ * ## 🛑 Why this exists, and why it only answers sometimes
+ *
+ * The gateway (online-payment) checkout prices shipping from the seller's
+ * stored policy and does not yet carry the buyer's per-store option — see the
+ * gap recorded at `createPhonePeGroupOrder`. Without this, every online order
+ * would carry NO `shippingObligation`, and `mayBookPlatformLabel` fails open on
+ * absence — so a seller who ships their own parcels could book a platform label
+ * against an order the buyer paid their custom rate for, which is the exact
+ * thing part C of the spec forbids.
+ *
+ * 🛑 It returns `null` whenever the offer leaves a genuine CHOICE (both axes
+ * enabled), because then the buyer's pick is the only thing that can decide and
+ * inventing one would record a contract nobody agreed to. It answers only when
+ * the seller offers exactly one method, where the method is a fact about the
+ * seller rather than a guess about the buyer.
+ *
+ * 🛑 It also returns `null` when nothing was charged. An obligation with no
+ * payment behind it would bind a seller to a price nobody paid.
+ */
+export function impliedObligation(offer, chargedAmount, shippingRequired) {
+    if (!shippingRequired)
+        return null;
+    if (!(chargedAmount > 0))
+        return null;
+    if (offer.customEnabled === offer.platformQuotesAccepted)
+        return null;
+    if (!offer.customEnabled)
+        return null;
+    return {
+        kind: "custom",
+        optionId: CUSTOM_SHIPPING_OPTION_ID,
+        chargedAmount,
+        label: offer.customLabel ?? "Seller's own shipping",
+        mustSelfFulfil: true,
+    };
+}
+/**
+ * May the seller book a PLATFORM label against this order?
+ *
+ * 🛑 The enforcement point for part C, and it reads the frozen obligation
+ * rather than re-deriving anything. Gated on what the buyer CHOSE, exactly as
+ * `isReimbursableShipment` is gated on who BOOKED — a fact about the
+ * transaction, never something the claimant supplies at claim time.
+ *
+ * Absence returns TRUE, i.e. fails open, and that is a prerequisite rather than
+ * a bug: no order written before this field existed carries it, and a
+ * fail-closed gate would refuse every seller on every historical order. The day
+ * the Shiprocket booking path is wired, THE SAME COMMIT must call this — see
+ * `isReimbursableShipment`'s note for the identical hazard on the identical
+ * shape.
+ */
+export function mayBookPlatformLabel(order) {
+    return order.shippingObligation?.mustSelfFulfil !== true;
+}
+/**
+ * Two decimal places. Money is stored as decimal rupees (Root Cause #31), so a
+ * seller typing `59.999` or a float artefact must not become a price with
+ * eleven decimal places on an invoice.
+ */
+function roundToPaise(value) {
+    return Math.round(value * 100) / 100;
+}

package/dist/_internal/shared/features/site-settings/fees.d.ts

@@ -40,10 +40,39 @@ export interface BuyerFacingFees {
     codHandlingFeeCap?: number;
     codHandlingFeePercent?: number;
     codDepositPercent?: number;
-    /** Commission rate applied to the cart subtotal, before the cap. */
+    /**
+     * 🛑 NOT the buyer-facing model any more (2026-11-08). The platform fee is
+     * `platformFeePerListingUnit × units`; this is the SELLER-side payout
+     * commission and is projected only so a legacy settings document can still
+     * be recognised. `explainPlatformFee` no longer reads it.
+     */
     platformFeePercent?: number;
-    /** Rupee ceiling on the commission — the reason a ₹39,500 order pays ₹10. */
+    /**
+     * 🛑 DEAD FOR CHECKOUT. It was the ceiling on the percentage model, and a ₹10
+     * ceiling on `n × ₹10` would cap every order at ₹10 — see
+     * `FeeCommissionRates.platformFeeMax`.
+     */
     platformFeeMax?: number;
+    /**
+     * The platform-fee VOLUME TAPER and its hard floor — owner, 2026-11-08.
+     *
+     * Buyer-facing by the same test as the rates above: the buyer pays it, so
+     * the buyer may check it. `explainPlatformFee` prints the band a line
+     * actually earned.
+     *
+     * 🛑 `toBuyerFacingFees` cannot project these yet: neither field exists on
+     * `SiteSettingsDocument["commissions"]`, and that schema belongs to another
+     * lane. Until it lands, the explainer is handed the per-line derivation the
+     * SERVER computed (`CheckoutPricingPreview.platformFeeLines`) rather than
+     * re-deriving it, so the explanation and the charge agree by construction
+     * rather than by coincidence. Declared here now so the projection is a
+     * two-line addition the day the schema fields exist.
+     */
+    platformFeeUnitBands?: readonly {
+        minUnits: number;
+        ratePerUnit: number;
+    }[];
+    platformFeePerUnitFloor?: number;
     /** GST rate levied on the commission actually charged (never on the uncapped figure). */
     gstPercent?: number;
     /** Rupee floor on `platformFee + gstOnFee` combined. */
@@ -52,7 +81,7 @@ export interface BuyerFacingFees {
 /**
  * Withheld on purpose (11 of 25): gatewayFeePercent, sellerShippingFixed,
  * platformShippingPercent, platformShippingFixedMin, autoPayoutWindowDays,
- * payoutHoldDays, minPayoutAmount, auctionListingFee, preOrderListingFee,
+ * payoutHoldDays, minPayoutAmount, collectorDropListingFee, preOrderListingFee,
  * featuredSlotFee, promotedSlotFee — plus `surchargeSellerSharePercent`, which
  * lives on the EMI block and is excluded by `BuyerEmiSettings` below.
  *

package/dist/_internal/shared/features/site-settings/fees.js

@@ -1,7 +1,7 @@
 /**
  * Withheld on purpose (11 of 25): gatewayFeePercent, sellerShippingFixed,
  * platformShippingPercent, platformShippingFixedMin, autoPayoutWindowDays,
- * payoutHoldDays, minPayoutAmount, auctionListingFee, preOrderListingFee,
+ * payoutHoldDays, minPayoutAmount, collectorDropListingFee, preOrderListingFee,
  * featuredSlotFee, promotedSlotFee — plus `surchargeSellerSharePercent`, which
  * lives on the EMI block and is excluded by `BuyerEmiSettings` below.
  *

package/dist/_internal/shared/features/site-settings/settings-preview-registry.d.ts

@@ -0,0 +1,17 @@
+export interface SettingsPreviewDef {
+    /** Stable id — the `RecentEntry.settingId` and the search result's dedupe key. */
+    id: string;
+    /** Literal `id="setting-*"` string this must match inside `AdminSiteSettingsView.tsx`. */
+    anchorId: string;
+    /** The real `<TabsContent value="...">` the anchor falls inside. */
+    tab: string;
+    label: string;
+    keywords?: string[];
+    /** Search ranking tiebreaker (9-ii) — see `rankNavSearchResults`'s own doc comment. Absent means 0. */
+    priority?: number;
+}
+export declare const SETTINGS_PREVIEW: SettingsPreviewDef[];
+export declare const SETTINGS_PREVIEW_IDS: string[];
+/** Build-time + runtime check that the two registries never overlap — see audit R3 for the enforced version. */
+export declare const SETTINGS_PREVIEW_TOGGLE_CATALOG_OVERLAP: string[];
+export declare function settingsPreviewById(id: string): SettingsPreviewDef | undefined;

package/dist/_internal/shared/features/site-settings/settings-preview-registry.js

@@ -0,0 +1,56 @@
+/**
+ * Phase 10 ("widget descriptors") — the READ-ONLY counterpart to
+ * `toggle-catalog.ts` (1A-vi, formerly `common-toggles.ts`). Every entry here
+ * is a site-settings value OUTSIDE the closed, write-capable `TOGGLE_CATALOG`
+ * registry, made findable on the dashboard without opening a second write
+ * path into the 20-tab form.
+ *
+ * 🛑 Selecting a card never flips anything. It navigates to
+ * `/admin/site-settings?tab={tab}#{anchorId}` and shows the CURRENT value as
+ * plain text, read from the already-fetched `["admin","site-settings"]`
+ * query cache — no new fetch, no new write endpoint, none of the form's
+ * cross-field validation (gateway ordering, COD/manual-payment dependencies)
+ * touched.
+ *
+ * Every `anchorId` below is verified against a real `id="setting-*"` literal
+ * in `AdminSiteSettingsView.tsx` (2026-11-02) — 13 anchors existed, all
+ * reused here; none invented. `tab` is the real `<TabsContent value="...">`
+ * each anchor falls inside, read directly off the file rather than guessed
+ * from the toggle's apparent subject (payment-gateway toggles are inside the
+ * `shipping` tab in this codebase, not a `payments` tab that doesn't exist —
+ * confirmed by line range, not assumed from the label).
+ *
+ * 🛑 `razorpay-enabled`/`phonepe-enabled`/`cashfree-enabled`/`cod-enabled`
+ * were REMOVED from here when 1A-vi widened `TOGGLE_CATALOG` from 3 to 18
+ * entries — all four are now write-capable toggle entries there, and keeping
+ * a second read-only copy with the same id would be exactly the
+ * two-registries-disagree risk this file's disjointness check exists to
+ * catch.
+ *
+ * `SETTINGS_PREVIEW_IDS` and `TOGGLE_CATALOG_IDS` must stay disjoint — this
+ * is what keeps "exactly one writable path" true. Enforced by
+ * `audit-widget-descriptor-sync.mjs` R3, not just by this comment.
+ */
+import { TOGGLE_CATALOG_IDS } from "./toggle-catalog.js";
+export const SETTINGS_PREVIEW = [
+    {
+        id: "robots-noindex",
+        anchorId: "setting-robots-noindex",
+        tab: "seo",
+        label: "Robots noindex",
+        keywords: ["seo", "search indexing", "google", "site settings"],
+    },
+    {
+        id: "daily-digest",
+        anchorId: "setting-daily-digest",
+        tab: "notifications",
+        label: "Daily status digest",
+        keywords: ["digest", "email", "staff", "site settings"],
+    },
+];
+export const SETTINGS_PREVIEW_IDS = SETTINGS_PREVIEW.map((s) => s.id);
+/** Build-time + runtime check that the two registries never overlap — see audit R3 for the enforced version. */
+export const SETTINGS_PREVIEW_TOGGLE_CATALOG_OVERLAP = SETTINGS_PREVIEW_IDS.filter((id) => TOGGLE_CATALOG_IDS.includes(id));
+export function settingsPreviewById(id) {
+    return SETTINGS_PREVIEW.find((s) => s.id === id);
+}

package/dist/_internal/shared/features/site-settings/toggle-catalog.d.ts

@@ -0,0 +1,68 @@
+/**
+ * TOGGLE_CATALOG — 1A-vi. Replaces `common-toggles.ts`'s hand-typed 3-entry
+ * array with the full, curated set of site-wide boolean switches on
+ * `SiteSettingsDocument`: payments, fee add-ons, tax, messaging channels,
+ * maintenance, chat, the assistant, support, the announcement bar — the
+ * owner's own "everything disableable, header to footer."
+ *
+ * 🛑 NOT build-time generated from the schema, deliberately. A brace-depth
+ * scan over a 1700-line interface cannot reliably tell a genuine top-level
+ * feature toggle (`chat.enabled`) from a config detail nested the same way
+ * (a color-overlay flag two levels deep) — confirmed during this phase's own
+ * discovery pass, which found `features.enabled` as a false positive (an
+ * array ITEM's own field, not a singleton group — and the whole `features`
+ * array is itself dead code, zero callers outside its own repository
+ * methods, flagged for Phase 8B deletion). `scripts/find-toggle-fields.mjs`
+ * is the discovery tool; this file is the human-curated result, kept honest
+ * by `audit-toggle-catalog-drift.mjs` re-running that same heuristic and
+ * failing if a listed `dotPath` stops resolving, OR if a newly-discovered
+ * candidate isn't yet triaged into (or explicitly excluded from) this list.
+ *
+ * The server-side write path (`PATCH /api/admin/site-settings/common-toggle/[id]`)
+ * still validates `id` against this closed array — a client cannot name an
+ * arbitrary `siteSettings.*` path to flip, same closed-set safety
+ * `common-toggles.ts` always had, just backed by 18 real entries instead of 3.
+ *
+ * @tag domain:site-settings
+ * @tag layer:shared
+ * @tag access:isomorphic
+ * @tag sideEffects:none
+ */
+import type { ActionConfirmation } from "../../actions/action-registry";
+export interface ToggleCatalogEntry {
+    /** Stable id — the route param, `RecentEntry.toggleId`, the search result's dedupe key. */
+    id: string;
+    /**
+     * The written path, always `{dotPath} = enabled`. For a `{group}.enabled`
+     * shape, `dotPath` IS `"{group}.enabled"`; for a flat `{group}.fooEnabled`
+     * shape, it is `"{group}.fooEnabled"` — either way, one dotted path,
+     * applied via `updateSingleton()`'s existing nested-write support
+     * (`toDottedPaths`), never a hand-built `{[group]: {enabled}}` object that
+     * only fits the first shape.
+     */
+    dotPath: string;
+    label: string;
+    /** Top-level `siteSettings` key — for display grouping only, not the write path. */
+    group: string;
+    keywords?: string[];
+    /**
+     * Search tiebreaker (1A-vi/9-ii, the Android-Settings reference: "only the
+     * important cards and toggles show up over the garbage stuff"). Default 0.
+     * Applied ONLY when `rankNavSearchResults`' match-quality score ties —
+     * never overrides an exact label match with a merely-important fuzzy one.
+     */
+    priority?: number;
+    /**
+     * 9K (overhaul brief, Phase 9-ii) — a mutating card/search-result toggle
+     * shows this confirm dialog before writing, same `ActionConfirmation`
+     * shape Rule #7 already requires for destructive `ActionDef`s. Set only on
+     * entries with a real external consequence (a site-wide gate, a payment
+     * method buyers rely on mid-checkout) — most toggles are genuinely inert
+     * and stay unconfirmed, matching Rule #7's own "skipped for anything
+     * genuinely inert" standard.
+     */
+    confirmation?: ActionConfirmation;
+}
+export declare const TOGGLE_CATALOG: ToggleCatalogEntry[];
+export declare function toggleCatalogById(id: string): ToggleCatalogEntry | undefined;
+export declare const TOGGLE_CATALOG_IDS: string[];