@mohasinac/appkit 4.59.0 → 4.60.1

package/dist/_internal/shared/features/print/label-profiles.js

@@ -0,0 +1,350 @@
+/*
+ * WHY: `PrintCenterView` sized its labels `w-[200px]` and emitted no `@page`
+ *      rule at all, so printing to a thermal label printer produced the
+ *      browser's default page — A4 — with a 200-pixel card floating in the
+ *      corner of it. Nothing errored. The operator discovered it by holding a
+ *      mostly-blank 50 x 25 mm label.
+ * WHAT: Every label stock this project can target, in MILLIMETRES, plus the
+ *       check that says whether a given payload actually fits on one.
+ *
+ * 🛑 IMPORTS `page-sizes.ts` RATHER THAN RESTATING IT. That module already owns
+ * `MM_PER_INCH`, `inchesToMm` and the A4/Letter geometry, and its own header
+ * explains why: three copies of a page table disagree the first time one of
+ * them is corrected, and the symptom is a print that is subtly the wrong size,
+ * discoverable only after it has been printed.
+ *
+ * EXPORTS:
+ *   LabelProfileId, LabelProfile, SheetLayout, LABEL_PROFILES,
+ *   LABEL_PROFILE_IDS, labelProfileById, labelPageCss, labelFitsProfile,
+ *   code128WidthMm, SAFE_MODULE_MM, MIN_SCANNABLE_MODULE_MM
+ *
+ * @tag domain:print
+ * @tag layer:shared
+ * @tag access:isomorphic
+ * @tag sideEffects:none
+ */
+import { MM_PER_INCH, PRINT_PAGE_SIZES, } from "../sticker-trace/export/page-sizes.js";
+// ── Barcode physics ─────────────────────────────────────────────────────────
+/**
+ * CODE128 module width at which essentially every handheld scanner reads
+ * reliably, including cheap CCD units at an angle. 0.25 mm ≈ 10 mil.
+ */
+export const SAFE_MODULE_MM = 0.25;
+/**
+ * The floor. Below this a symbol is a lottery: good scanners manage it under
+ * good light at a good angle, and a receive station is none of those things.
+ */
+export const MIN_SCANNABLE_MODULE_MM = 0.19;
+/**
+ * How wide a CODE128-B symbol must be, in mm, INCLUDING its quiet zones.
+ *
+ * Structure, from the symbology itself rather than from a chart:
+ *   start   11 modules
+ *   each data character 11 modules
+ *   check   11 modules
+ *   stop    13 modules
+ *   quiet   10 modules each side (the spec minimum)
+ *
+ * so `11 x (n + 2) + 13 + 20` modules for `n` data characters.
+ *
+ * 🛑 THE QUIET ZONE IS PART OF THE SYMBOL, not padding around it. A label sized
+ * to the bars alone prints a barcode whose first bar touches the die-cut edge,
+ * and a scanner has nothing to lock onto — it reads as a smudged or damaged
+ * label rather than as a layout mistake.
+ *
+ * 🛑 This also CORRECTS a number already written down elsewhere. The
+ * barcode-vs-SKU header in `id-generators.ts` derives "a ~42 mm minimum" from
+ * the 12-character `LIR-XXXXXXXX` form; that figure omits the quiet zones.
+ * 11 x 14 + 13 = 167 modules of bars, but 187 with them, which is 46.75 mm at
+ * `SAFE_MODULE_MM` — not 42. The smaller figure is the dangerous direction to
+ * be wrong in, because it says yes to stock that cannot carry the symbol.
+ */
+export function code128WidthMm(characters, moduleMm = SAFE_MODULE_MM) {
+    if (!(characters > 0)) {
+        throw new Error(`code128WidthMm: characters must be > 0 (got ${characters})`);
+    }
+    if (!(moduleMm > 0)) {
+        throw new Error(`code128WidthMm: moduleMm must be > 0 (got ${moduleMm})`);
+    }
+    const modules = 11 * (characters + 2) + 13 + 20;
+    return modules * moduleMm;
+}
+/*
+ * 🛑 THE A4 SHEET GEOMETRY BELOW IS FROM AVERY'S PUBLISHED TEMPLATE SPECS, NOT
+ * MEASURED. That distinction matters more here than almost anywhere else in
+ * this codebase: a pitch that is wrong by half a millimetre is invisible on
+ * label one and has drifted off the die-cut entirely by label thirteen, and the
+ * cost is a whole sheet of label stock per attempt.
+ *
+ * PRINT ONE SHEET ON PLAIN PAPER AND HOLD IT AGAINST THE LABEL STOCK BEFORE ANY
+ * BATCH RUN. That is the only check that settles it, and it costs one sheet of
+ * paper. Corrections belong here, with the date and the stock they were
+ * measured against.
+ */
+const A4 = PRINT_PAGE_SIZES.a4;
+const a4Page = { widthMm: A4.widthMm, heightMm: A4.heightMm };
+/** Thermal page = one label, so margins are zero by construction. */
+function thermal(id, label, widthMm, heightMm) {
+    return {
+        id,
+        label,
+        widthMm,
+        heightMm,
+        /*
+         * 1.5 mm, which is a DIE-CUT tolerance rather than a design margin.
+         * Thermal label rolls wander laterally by about a millimetre as they feed,
+         * so ink placed closer than this to the edge lands on the liner on some
+         * labels and not others — the defect appears on one label in ten and reads
+         * as a printer fault.
+         */
+        paddingMm: 1.5,
+        page: { widthMm, heightMm },
+        sheet: null,
+        isThermal: true,
+    };
+}
+export const LABEL_PROFILES = {
+    "thermal-50x25": thermal("thermal-50x25", "Thermal roll 50 x 25 mm", 50, 25),
+    "thermal-38x25": thermal("thermal-38x25", "Thermal roll 38 x 25 mm", 38, 25),
+    "thermal-100x50": thermal("thermal-100x50", "Thermal roll 100 x 50 mm (box labels)", 100, 50),
+    "a4-65up": {
+        id: "a4-65up",
+        label: "A4 sheet, 65-up (38.1 x 21.2 mm — Avery L7651)",
+        widthMm: 38.1,
+        heightMm: 21.2,
+        paddingMm: 1,
+        page: a4Page,
+        sheet: {
+            columns: 5,
+            rows: 13,
+            marginLeftMm: 4.65,
+            marginTopMm: 10.7,
+            pitchXMm: 40.6,
+            pitchYMm: 21.2,
+        },
+        isThermal: false,
+    },
+    "a4-24up": {
+        id: "a4-24up",
+        label: "A4 sheet, 24-up (63.5 x 33.9 mm — Avery L7159)",
+        widthMm: 63.5,
+        heightMm: 33.9,
+        paddingMm: 1.5,
+        page: a4Page,
+        sheet: {
+            columns: 3,
+            rows: 8,
+            marginLeftMm: 7.1,
+            marginTopMm: 13.1,
+            pitchXMm: 66.0,
+            pitchYMm: 34.0,
+        },
+        isThermal: false,
+    },
+    "a4-8up": {
+        id: "a4-8up",
+        label: "A4 sheet, 8-up (99.1 x 67.7 mm — Avery L7165)",
+        widthMm: 99.1,
+        heightMm: 67.7,
+        paddingMm: 2,
+        page: a4Page,
+        sheet: {
+            columns: 2,
+            rows: 4,
+            marginLeftMm: 4.65,
+            marginTopMm: 13.1,
+            pitchXMm: 101.6,
+            pitchYMm: 67.7,
+        },
+        isThermal: false,
+    },
+};
+/** Thermal first — it is what the warehouse actually uses day to day. */
+export const LABEL_PROFILE_IDS = [
+    "thermal-50x25",
+    "thermal-38x25",
+    "thermal-100x50",
+    "a4-65up",
+    "a4-24up",
+    "a4-8up",
+];
+export function labelProfileById(id) {
+    return LABEL_PROFILES[id];
+}
+// ── The @page rule ──────────────────────────────────────────────────────────
+/**
+ * The real print geometry, as CSS.
+ *
+ * 🛑 `@page { size: <w>mm <h>mm; margin: 0 }` IS THE WHOLE POINT OF THIS
+ * MODULE. Without it the browser prints the user's default paper and the label
+ * is a small rectangle somewhere on an A4 sheet. `margin: 0` is not tidiness:
+ * a thermal page IS one label, so any page margin shrinks the label and the
+ * content no longer lines up with the die-cut.
+ *
+ * 🛑 `@page` IS DOCUMENT-GLOBAL AND CANNOT BE SCOPED. Two components each
+ * emitting one does not give two geometries — the later in document order
+ * wins, silently. So exactly ONE owner may call this per printable view, and
+ * that owner is the thing that knows which profile the user picked.
+ *
+ * The screen preview is deliberately NOT styled from here. A label shown at its
+ * true physical size on a 27-inch monitor is a postage stamp nobody can read,
+ * and mm in a browser depend on a reported DPI that is usually a guess.
+ */
+export function labelPageCss(profile) {
+    const { widthMm, heightMm } = profile.page;
+    return [
+        `@page { size: ${widthMm}mm ${heightMm}mm; margin: 0; }`,
+        `@media print {`,
+        `  html, body { margin: 0; padding: 0; }`,
+        `  .no-print { display: none !important; }`,
+        /*
+         * One label per page on thermal: the printer advances to the next label on
+         * a page break, so a break after each one is what keeps content and
+         * die-cut aligned. On a sheet the labels are positioned within one page
+         * instead, so breaking after each would waste 64 of 65.
+         */
+        profile.isThermal
+            ? `  .appkit-label { break-after: page; page-break-after: always; }`
+            : `  .appkit-label-sheet { break-inside: avoid; page-break-inside: avoid; }`,
+        `  .appkit-label { break-inside: avoid; page-break-inside: avoid; }`,
+        `}`,
+    ].join("\n");
+}
+/**
+ * The `@page` rule for an ordinary printed DOCUMENT — a packing slip, a box
+ * contents sheet — rather than a label.
+ *
+ * 🛑 Lives here rather than in the view for one reason: `audit-label-profiles`
+ * R3 allows exactly one module to author `@page`, because the rule is
+ * document-global and a second author does not add a geometry — the later one
+ * silently wins. A view that needed A4 would otherwise have to write its own
+ * and defeat that guarantee.
+ *
+ * 🛑 It takes explicit mm, never `size: A4`. A named paper size is the original
+ * bug this module exists to fix: the browser prints its default page, which is
+ * A4 for some users and Letter for others, and the layout silently differs by
+ * 18 mm of height between them.
+ */
+export function documentPageCss(page = {
+    widthMm: PRINT_PAGE_SIZES.a4.widthMm,
+    heightMm: PRINT_PAGE_SIZES.a4.heightMm,
+}, marginMm = 0) {
+    return [
+        `@page { size: ${page.widthMm}mm ${page.heightMm}mm; margin: ${marginMm}mm; }`,
+        `@media print {`,
+        `  html, body { margin: 0; padding: 0; }`,
+        `  .no-print { display: none !important; }`,
+        `  .appkit-label-sheet { break-inside: avoid; page-break-inside: avoid; }`,
+        `}`,
+    ].join("\n");
+}
+/**
+ * Does a barcode of `characters` length fit this label — and if not, why.
+ *
+ * 🛑 THIS REPORTS. IT NEVER SCALES, AND THAT IS THE ENTIRE DESIGN.
+ *
+ * Scaling a barcode to fit is the obvious, wrong answer, and it fails in the
+ * worst possible way: the label looks perfect. The bars are narrower, the
+ * proportions are right, a human sees a barcode — and the module width has
+ * dropped below what a scanner can resolve, so it does not read. The failure
+ * surfaces weeks later at a receive station as "the scanner is broken", and the
+ * labels have all been printed and stuck to things by then.
+ *
+ * A refusal to print is noticed in the second it happens, by the person who can
+ * still choose different stock. That is the only trade this function makes.
+ *
+ * 🛑 COMPUTED AGAINST THE PROFILES ABOVE, NOT ASSERTED. A 12-character
+ * `LIR-XXXXXXXX` symbol needs 187 modules = 46.75 mm at `SAFE_MODULE_MM`, and
+ * the six stocks answer differently enough that a single "does it fit" boolean
+ * would have been a lie:
+ *
+ *   thermal-100x50   97.0 mm   0.519 mm/module   comfortable
+ *   a4-8up           95.1 mm   0.509 mm/module   comfortable
+ *   a4-24up          60.5 mm   0.324 mm/module   comfortable
+ *   thermal-50x25    47.0 mm   0.251 mm/module   fits by 0.25 mm — no slack
+ *   a4-65up          36.1 mm   0.193 mm/module   over the floor by 0.003 mm
+ *   thermal-38x25    35.0 mm   0.187 mm/module   BELOW the floor
+ *
+ * 🛑 An earlier draft of this comment claimed `a4-65up` "cannot carry" the
+ * symbol. It can, barely — 0.193 against a 0.19 floor — and overstating it
+ * would have had someone discard working stock. The two genuinely notable rows
+ * are the last two, and they are notable for opposite reasons: 65-up is
+ * technically above the floor with no margin whatsoever for a worn printhead,
+ * and 38x25 is the one stock that simply cannot do it.
+ *
+ * All six stay in the list. 38x25 is fine for a shorter code or a text-only
+ * label, and silently dropping stock the warehouse already owns teaches nobody
+ * why it was dropped.
+ */
+export function labelFitsProfile(profile, characters) {
+    const availableMm = profile.widthMm - profile.paddingMm * 2;
+    const requiredMm = code128WidthMm(characters, SAFE_MODULE_MM);
+    const modules = 11 * (characters + 2) + 13 + 20;
+    const impliedModuleMm = availableMm / modules;
+    const fits = availableMm >= requiredMm;
+    if (fits) {
+        return {
+            fits: true,
+            requiredMm,
+            availableMm,
+            impliedModuleMm,
+            reason: `${characters}-character barcode fits ${profile.label} with ${(availableMm - requiredMm).toFixed(1)} mm to spare.`,
+        };
+    }
+    /*
+     * Two different refusals, because they have different remedies. "Too narrow
+     * but still scannable" means the stock works and the margin is thin; "below
+     * the scanning floor" means no amount of care will make it read, and the
+     * answer is different stock or a shorter code.
+     */
+    const scannable = impliedModuleMm >= MIN_SCANNABLE_MODULE_MM;
+    return {
+        fits: false,
+        requiredMm,
+        availableMm,
+        impliedModuleMm,
+        reason: scannable
+            ? `${profile.label} offers ${availableMm.toFixed(1)} mm of printable width; a ${characters}-character CODE128 needs ${requiredMm.toFixed(1)} mm at a comfortable density. It would print at ${impliedModuleMm.toFixed(3)} mm per module — above the ${MIN_SCANNABLE_MODULE_MM} mm floor, so it should still scan, but with no margin for a worn printhead or an angled read.`
+            : `${profile.label} cannot carry a ${characters}-character CODE128. It offers ${availableMm.toFixed(1)} mm against the ${requiredMm.toFixed(1)} mm needed, which would force ${impliedModuleMm.toFixed(3)} mm per module — below the ${MIN_SCANNABLE_MODULE_MM} mm scanning floor. Pick wider stock, or shorten the code.`,
+    };
+}
+/**
+ * Where label `index` sits on a sheet, in mm from the page's top-left.
+ *
+ * Returns null past the last position on the sheet, which the caller must read
+ * as "start a new page" rather than as an error — a 70-label job on 65-up stock
+ * is two pages, not a failure.
+ */
+export function sheetPositionMm(sheet, index) {
+    const perPage = sheet.columns * sheet.rows;
+    if (index < 0 || index >= perPage)
+        return null;
+    const col = index % sheet.columns;
+    const row = Math.floor(index / sheet.columns);
+    return {
+        leftMm: sheet.marginLeftMm + col * sheet.pitchXMm,
+        topMm: sheet.marginTopMm + row * sheet.pitchYMm,
+    };
+}
+/**
+ * Sanity check that a sheet's own grid fits on its own page.
+ *
+ * 🛑 Exists because the Avery figures above are transcribed, and a transposed
+ * digit in a pitch is invisible until a batch has been printed. The last
+ * label's far edge is `margin + (n - 1) x pitch + size`; if that exceeds the
+ * page, the grid is wrong on paper and nothing else in this module would say
+ * so. Call it from the audit, not at render time.
+ */
+export function sheetOverflowMm(profile) {
+    const s = profile.sheet;
+    if (!s)
+        return null;
+    const right = s.marginLeftMm + (s.columns - 1) * s.pitchXMm + profile.widthMm;
+    const bottom = s.marginTopMm + (s.rows - 1) * s.pitchYMm + profile.heightMm;
+    return {
+        rightMm: right - profile.page.widthMm,
+        bottomMm: bottom - profile.page.heightMm,
+    };
+}
+/** Re-exported so a caller converting a legacy inch figure need not hunt. */
+export { MM_PER_INCH };

package/dist/_internal/shared/features/products/to-product-item.js

@@ -20,17 +20,45 @@
  * rather than a barrel. Keep this file free of any server-only import so a
  * client component can always call it directly.
  */
+/*
+ * Client-safe: `products/schemas/firestore.ts` imports only `id-generators`
+ * as a value (pure, `globalThis.crypto`) plus erased types — it does not reach
+ * `providers/db-firebase`, so the header's rule above still holds. Checked
+ * rather than assumed, because that rule is what this file exists for.
+ */
+import { productImageUrls } from "../../../../features/products/schemas/firestore.js";
 export function toProductItem(doc) {
     return {
         id: String(doc.id ?? ""),
         title: String(doc.title ?? doc.name ?? ""),
         price: typeof doc.price === "number" ? doc.price : 0,
         originalPrice: typeof doc.originalPrice === "number" ? doc.originalPrice : undefined,
-        mainImage: Array.isArray(doc.images)
-            ? doc.images[0]
-            : typeof doc.mainImage === "string"
-                ? doc.mainImage
-                : undefined,
+        /*
+         * 🛑 `images` is `ProductImage[]` — OBJECTS — not `string[]`.
+         *
+         * This read `doc.images[0] as string`, and the cast is what hid it from
+         * the compiler. `MediaImage` then received `{ url: "/media/…" }`,
+         * `resolveMediaUrl` type-guarded the non-string and returned `undefined`,
+         * and every related card rendered the 📦 placeholder — with **no network
+         * request at all**, which is what distinguishes this from a genuine 404
+         * (those retry three times before latching).
+         *
+         * Blast radius was every related carousel on all seven listing-type
+         * detail pages, plus `GroupedListingsCarousel` and
+         * `FranchiseDetailPageView`. The PDP gallery had already been fixed for
+         * the identical reason and its comment says so; this was the last site
+         * still doing `doc.images[0] as string`.
+         *
+         * `mainImage` FIRST, gallery as fallback — the seller chose `mainImage`
+         * deliberately, and this matches the precedence every other card mapper
+         * uses (e.g. `StoreAuctionsListing`). `productImageUrls` is the one
+         * normaliser and it also accepts the legacy `string[]`.
+         */
+        mainImage: (typeof doc.mainImage === "string" ? doc.mainImage : undefined) ??
+            productImageUrls(doc.images)[0],
+        // Carried so a card that needs a second image does not have to re-read the
+        // document. Previously dropped entirely, which left the tile no fallback.
+        images: productImageUrls(doc.images),
         status: doc.status ?? "published",
         slug: typeof doc.slug === "string" ? doc.slug : undefined,
         storeName: typeof doc.storeName === "string" ? doc.storeName : undefined,

package/dist/_internal/shared/fees/calculator.d.ts

@@ -70,10 +70,39 @@ export interface PayoutDeduction {
     gstOnFee: number;
     /** platformFee + gatewayFee + gstOnFee. */
     totalDeduction: number;
-    /** grossAmount - totalDeduction, floored at 0. */
+    /** grossAmount - totalDeduction + shippingReimbursement, floored at 0. */
     netAmount: number;
+    /**
+     * Postage refunded to the seller, added AFTER the deductions (D45).
+     *
+     * Reported separately so a payout can be explained: "₹951 goods less ₹10 fee
+     * plus ₹80 postage" is a sentence; one net figure is not.
+     */
+    shippingReimbursement: number;
 }
-export declare function computePayoutDeduction(grossAmount: number, commissions: FeeCommissionRates): PayoutDeduction;
+/**
+ * What a seller is actually paid.
+ *
+ * ## 🛑 `shippingReimbursement` is added AFTER the fee bases, never into them
+ *
+ * D45 makes postage a **cost being refunded**, not revenue. So it is the one
+ * term in this function that is added to `netAmount` while being excluded from
+ * `platformFee` and `gatewayFee` — because commissioning a seller's postage
+ * would mean charging them for the privilege of posting the parcel, and taking
+ * a gateway percentage of it would mean charging them a card fee on money that
+ * is reimbursing a cash outlay.
+ *
+ * That is also why it is a parameter here rather than something a caller adds
+ * to `grossAmount` before calling: `grossAmount` IS the commission base, so
+ * folding postage into it silently commissions it. Four payout paths call this
+ * (the seller's own earnings view, the manual request, and both jobs) and all
+ * four must agree to the rupee — a seller shown one number and paid another is
+ * worse than either number being wrong alone. One owner is what guarantees it.
+ *
+ * Defaulted to 0, so the three call sites that do not yet pass it keep their
+ * current behaviour exactly rather than silently gaining a term.
+ */
+export declare function computePayoutDeduction(grossAmount: number, commissions: FeeCommissionRates, shippingReimbursement?: number): PayoutDeduction;
 export interface CodHandlingFeeRates {
     /**
      * Rupee CEILING on the COD handling fee. Optional so a `siteSettings`

package/dist/_internal/shared/fees/calculator.js

@@ -15,6 +15,7 @@
  * All money amounts are in decimal rupees.
  */
 import { roundRupees } from "../../../utils/number.formatter.js";
+import { resolveStateKey } from "./india-states.js";
 /** Buyer-facing platform commission ceiling, in decimal rupees. */
 const DEFAULT_PLATFORM_FEE_MAX = 10;
 /**
@@ -49,7 +50,34 @@ export function allocateCheckoutFees(groupSubtotals, fees) {
     if (groupSubtotals.length === 0)
         return allocation;
     const total = groupSubtotals.reduce((sum, [, subtotal]) => sum + subtotal, 0);
-    let platformRemaining = fees.platformFee;
+    /*
+     * ── D41: THE `minimumTransactionFee` FLOOR IS APPLIED HERE, ONCE ──────────
+     *
+     * `computeCheckoutFees` computes `totalFee = max(platformFee + gstOnFee,
+     * minimumTransactionFee)` — and **`totalFee` had ZERO consumers.** Measured:
+     * the only references were its own declaration, its computation and its
+     * return. So the floor existed in a field nothing read.
+     *
+     * The capture route re-derived it by hand instead
+     * (`max(rawTotal, discountedSubtotal + minimumTransactionFee + …)`), while
+     * this allocator apportioned the UNFLOORED `platformFee`/`gstOnFee` to each
+     * order group. Consequence where the floor bit: **the gateway captured the
+     * floored amount and the orders recorded less than was collected.** The
+     * buyer's statement and our own records disagreed, by exactly the shortfall.
+     *
+     * The shortfall is treated as additional PLATFORM FEE, with no GST of its
+     * own, because the floor is defined on `platformFee + gstOnFee` COMBINED —
+     * so `flooredPlatformFee + gstOnFee` is exactly `totalFee`, which is exactly
+     * what the capture route charges. Adding GST on top of the shortfall would
+     * push the captured total above the floor and reintroduce the mismatch in
+     * the other direction.
+     *
+     * A floor nothing applies is not a floor; a floor applied in one of two
+     * places is worse, because the two then disagree about money.
+     */
+    const feeShortfall = Math.max(0, roundRupees(fees.totalFee - (fees.platformFee + fees.gstOnFee)));
+    const flooredPlatformFee = roundRupees(fees.platformFee + feeShortfall);
+    let platformRemaining = flooredPlatformFee;
     let gstRemaining = fees.gstOnFee;
     groupSubtotals.forEach(([storeId, subtotal], index) => {
         const isLast = index === groupSubtotals.length - 1;
@@ -57,7 +85,7 @@ export function allocateCheckoutFees(groupSubtotals, fees) {
         // whole (necessarily zero-ish) fee to the last group rather than dividing
         // by zero.
         const share = total > 0 ? subtotal / total : 0;
-        const platformFee = isLast ? roundRupees(platformRemaining) : roundRupees(fees.platformFee * share);
+        const platformFee = isLast ? roundRupees(platformRemaining) : roundRupees(flooredPlatformFee * share);
         const gstOnFee = isLast ? roundRupees(gstRemaining) : roundRupees(fees.gstOnFee * share);
         platformRemaining = roundRupees(platformRemaining - platformFee);
         gstRemaining = roundRupees(gstRemaining - gstOnFee);
@@ -65,13 +93,45 @@ export function allocateCheckoutFees(groupSubtotals, fees) {
     });
     return allocation;
 }
-export function computePayoutDeduction(grossAmount, commissions) {
+/**
+ * What a seller is actually paid.
+ *
+ * ## 🛑 `shippingReimbursement` is added AFTER the fee bases, never into them
+ *
+ * D45 makes postage a **cost being refunded**, not revenue. So it is the one
+ * term in this function that is added to `netAmount` while being excluded from
+ * `platformFee` and `gatewayFee` — because commissioning a seller's postage
+ * would mean charging them for the privilege of posting the parcel, and taking
+ * a gateway percentage of it would mean charging them a card fee on money that
+ * is reimbursing a cash outlay.
+ *
+ * That is also why it is a parameter here rather than something a caller adds
+ * to `grossAmount` before calling: `grossAmount` IS the commission base, so
+ * folding postage into it silently commissions it. Four payout paths call this
+ * (the seller's own earnings view, the manual request, and both jobs) and all
+ * four must agree to the rupee — a seller shown one number and paid another is
+ * worse than either number being wrong alone. One owner is what guarantees it.
+ *
+ * Defaulted to 0, so the three call sites that do not yet pass it keep their
+ * current behaviour exactly rather than silently gaining a term.
+ */
+export function computePayoutDeduction(grossAmount, commissions, shippingReimbursement = 0) {
     const platformFee = roundRupees(grossAmount * (commissions.platformFeePercent / 100));
     const gatewayFee = roundRupees(grossAmount * ((commissions.gatewayFeePercent ?? 0) / 100));
     const gstOnFee = roundRupees(platformFee * (commissions.gstPercent / 100));
     const totalDeduction = roundRupees(platformFee + gatewayFee + gstOnFee);
-    const netAmount = Math.max(0, roundRupees(grossAmount - totalDeduction));
-    return { platformFee, gatewayFee, gstOnFee, totalDeduction, netAmount };
+    const postage = Number.isFinite(shippingReimbursement)
+        ? Math.max(0, shippingReimbursement)
+        : 0;
+    const netAmount = Math.max(0, roundRupees(grossAmount - totalDeduction + postage));
+    return {
+        platformFee,
+        gatewayFee,
+        gstOnFee,
+        totalDeduction,
+        netAmount,
+        shippingReimbursement: roundRupees(postage),
+    };
 }
 /** Buyer-facing COD handling ceiling, in decimal rupees. */
 const DEFAULT_COD_HANDLING_FEE_CAP = 200;
@@ -183,6 +243,44 @@ export const DEFAULT_GST_RATE = 5;
  * than guess.
  */
 export function isIntraStateSupply(storeState, buyerState) {
+    /*
+     * ── G2: resolve through the state TABLE first, not string equality ───────
+     *
+     * This was `normaliseStateName(a) === normaliseStateName(b)` — lowercase,
+     * strip non-letters, compare. Correct only when both sides happen to be
+     * spelled the same way, and they are not: a seller types their pickup
+     * state, a buyer types their delivery state, and a GSTIN carries the state
+     * as a two-digit CODE. So `"KA"` vs `"Karnataka"` compared unequal and the
+     * supply read as INTER-state, recording **IGST where CGST+SGST was due**.
+     *
+     * Worse, the old normaliser's `.replace(/[^a-z\s]/g, " ")` DESTROYED
+     * digits, so a state held as `"29"` — or a full GSTIN — normalised to the
+     * empty string and returned `null`, i.e. "place of supply undetermined",
+     * which both callers then resolve to IGST with a warning.
+     *
+     * None of this changed the TOTAL (IGST total == CGST+SGST total), which is
+     * precisely why it could live indefinitely: no figure in the system
+     * disagreed with any other. Only the split was wrong, and the split is what
+     * a GST return is built from.
+     *
+     * Verified against the table: "KA", "29", "29ABCDE1234F1Z5" and
+     * "karnataka." all resolve to one key; "AP" vs "Arunachal Pradesh", "MP" vs
+     * "Maharashtra" and "Punjab" vs "Puducherry" stay distinct (7 negative
+     * controls, 0 false positives).
+     */
+    const keyA = resolveStateKey(storeState);
+    const keyB = resolveStateKey(buyerState);
+    if (keyA && keyB)
+        return keyA === keyB;
+    /*
+     * 🛑 The string fallback STAYS, and it is a widening rather than a
+     * replacement. An input the table cannot resolve — a typo, a non-Indian
+     * state — used to be handled by plain equality, and for the case where BOTH
+     * sides carry the SAME unrecognised spelling ("Karnatka" twice) that
+     * produced the right answer. Dropping it would turn those into
+     * "undetermined", which resolves to IGST, so a pure replacement would
+     * REGRESS exactly the inputs the table was added to improve.
+     */
     const a = normaliseStateName(storeState);
     const b = normaliseStateName(buyerState);
     if (!a || !b)