@mohasinac/appkit 4.59.0 → 4.60.0

package/dist/_internal/shared/checkout/refundable-base.js

@@ -0,0 +1,122 @@
+/**
+ * How much of an order can still be refunded, and what is withheld.
+ *
+ * ONE owner for two numbers that were previously computed four different ways
+ * and disagreed with each other and with the money actually moved.
+ *
+ * WHY:
+ *
+ * · **D1** — the over-refund guard compared `amount > order.totalPrice`, i.e.
+ *   against the ORDER TOTAL rather than the remaining balance, while its own
+ *   docstring promised "≤ remaining refundable amount". So ₹500 and then
+ *   another ₹500 both passed on a ₹600 order: **₹1,000 refunded, two real
+ *   gateway calls, both successful.**
+ *
+ * · **D3** — `isFull` was `amount >= order.totalPrice`, so a split refund
+ *   (₹300 + ₹200 of ₹500) never reached `status: "refunded"` and the order
+ *   stayed fully refundable forever.
+ *
+ * · **D32** — the platform fee is non-refundable by policy, and the only code
+ *   implementing that withheld ~10x too much (see `platformFeeWithheld`).
+ */
+import { roundRupees } from "../../../utils/number.formatter.js";
+/**
+ * Half a paisa. The tolerance exists because these are IEEE-754 sums of 2dp
+ * components: `0.1 + 0.2 > 0.3` is TRUE in floating point, so an exact
+ * comparison would reject a legitimate final refund that exactly exhausts the
+ * balance. Half a paisa is below the smallest representable money unit, so it
+ * cannot admit a real over-refund.
+ */
+export const MONEY_EPSILON = 0.005;
+/**
+ * The platform fee actually withheld on a refund: the amount CHARGED, never a
+ * recomputed percentage.
+ *
+ * 🛑 This replaces the single worst money defect found in the audit (D32).
+ * `previewCancellationRefund` did:
+ *
+ *     const effectiveRate = platformFeePercent * (1 + gstPercent / 100);
+ *     const feeDeducted   = (grossRefund * effectiveRate) / 100;
+ *
+ * — a PERCENTAGE OF THE REFUND, which ignores `commissions.platformFeeMax`
+ * (default **₹10**) entirely and ignores `order.platformFee`, the amount that
+ * was actually collected and is stored on the order. On a ₹5,000 order at 2% +
+ * 18% GST it deducted **₹118** from a buyer who had paid **₹11.80** — keeping
+ * roughly ₹106 of their goods money and labelling it a platform fee. The
+ * overcharge grows with order value, so it is largest exactly where it is most
+ * noticeable.
+ *
+ * `platformFeeGst` is read from the order and only DERIVED for rows written
+ * before that field existed (2026-10-21). The derivation takes `gstPercent`
+ * from the caller rather than reading settings itself, so this stays pure and
+ * so a caller cannot accidentally reach for today's rate when the order is
+ * from last year — which is the mistake the whole function exists to undo.
+ */
+export function platformFeeWithheld(order, 
+/** Only consulted for legacy orders with no stored `platformFeeGst`. */
+legacyGstPercent) {
+    const fee = order.platformFee ?? 0;
+    if (fee <= 0)
+        return 0;
+    const gst = order.platformFeeGst ??
+        (typeof legacyGstPercent === "number" ? roundRupees((fee * legacyGstPercent) / 100) : 0);
+    return roundRupees(fee + gst);
+}
+/**
+ * The ceiling every refund is measured against.
+ *
+ * 🛑 `totalPrice − platformFeeWithheld`, NOT `totalPrice`. The platform fee is
+ * non-refundable in every scenario — a decided policy, and one the product
+ * already states: `REFUND_COPY.request.acknowledgments[2]` tells the buyer
+ * "platform fees may be non-recoverable".
+ *
+ * This correction matters twice over. Phase 1's cumulative cap has to compare
+ * against THIS, or a refund can exceed what the buyer is owed; and `isFull`
+ * has to compare against THIS, or the largest possible refund is strictly less
+ * than `totalPrice` and **an order can never reach `status: "refunded"`** —
+ * which is what the old `amount >= totalPrice` test guaranteed.
+ */
+export function refundableBase(order, legacyGstPercent) {
+    return roundRupees(Math.max(0, order.totalPrice - platformFeeWithheld(order, legacyGstPercent)));
+}
+/**
+ * Sum of refunds that have COMMITTED money, i.e. everything not `failed`.
+ *
+ * 🛑 A `reserved` entry counts. The two-phase write reserves before calling the
+ * provider and settles after, so between those two points the money may well
+ * have left — excluding reserved entries would let a concurrent request refund
+ * against a balance that is already spoken for, which is the TOCTOU the
+ * reservation exists to close. A `failed` entry releases its reservation by
+ * being skipped here, which is why no explicit release step is needed.
+ *
+ * `status` is optional on `OrderRefundEvent`: rows written before the
+ * two-phase scheme have none, and those are all committed refunds, so a
+ * missing status must count.
+ */
+export function committedRefundTotal(order) {
+    return roundRupees((order.refunds ?? [])
+        .filter((r) => r.status !== "failed")
+        .reduce((sum, r) => sum + (r.amount ?? 0), 0));
+}
+/** Everything a caller needs to decide and to EXPLAIN a refund decision. */
+export function refundCapacity(order, legacyGstPercent) {
+    const base = refundableBase(order, legacyGstPercent);
+    const committed = committedRefundTotal(order);
+    return {
+        base,
+        committed,
+        remaining: roundRupees(Math.max(0, base - committed)),
+        withheld: platformFeeWithheld(order, legacyGstPercent),
+    };
+}
+/**
+ * Would this refund exhaust the refundable base?
+ *
+ * Measured against `base`, not `totalPrice` — see `refundableBase`. The
+ * epsilon makes an exactly-exhausting refund count as full rather than
+ * leaving a sub-paisa residue that keeps the order refundable forever.
+ */
+export function wouldBeFullRefund(order, amount, legacyGstPercent) {
+    const { base, committed } = refundCapacity(order, legacyGstPercent);
+    return committed + amount >= base - MONEY_EPSILON;
+}

package/dist/_internal/shared/features/auctions/config.d.ts

@@ -55,6 +55,19 @@ export interface BuyNowAvailabilityInput {
     currentBid: number | null | undefined;
     isEnded: boolean;
     isSold?: boolean;
+    /**
+     * The seller's floor for the item (D53). Buy-Now below it is refused.
+     *
+     * 🛑 OPTIONAL so every existing call site keeps compiling — but a caller
+     * that has the product and omits it silently reopens the hole, which is the
+     * weakness of this shape. The two server call sites that decide money
+     * (`placeBuyNow`, and the capability gate it consults) both pass it; a
+     * display-only caller that omits it renders a button the server will refuse,
+     * which is a worse UX than a hidden button but is not an exploit.
+     *
+     * Absent / 0 / non-finite means NO reserve — the common case.
+     */
+    reservePrice?: number | null;
 }
 /**
  * The single definition of "can this auction be bought outright right now".
@@ -75,7 +88,7 @@ export interface BuyNowAvailabilityInput {
  * `isSold` is optional because client callers rendering a live auction page
  * already know it isn't sold; server callers should always pass it.
  */
-export declare function isBuyNowAvailable({ buyNowPrice, currentBid, isEnded, isSold, }: BuyNowAvailabilityInput): boolean;
+export declare function isBuyNowAvailable({ buyNowPrice, currentBid, isEnded, isSold, reservePrice, }: BuyNowAvailabilityInput): boolean;
 /**
  * Preset step multipliers offered by the bid form, as multiples of the
  * effective minimum increment. With a ₹100 increment this renders

package/dist/_internal/shared/features/auctions/config.js

@@ -89,12 +89,41 @@ export function resolveMinBid(currentBidAmount, tiers, override, opts) {
  * `isSold` is optional because client callers rendering a live auction page
  * already know it isn't sold; server callers should always pass it.
  */
-export function isBuyNowAvailable({ buyNowPrice, currentBid, isEnded, isSold, }) {
+export function isBuyNowAvailable({ buyNowPrice, currentBid, isEnded, isSold, reservePrice, }) {
     if (isEnded || isSold === true)
         return false;
     if (typeof buyNowPrice !== "number" || !Number.isFinite(buyNowPrice) || buyNowPrice <= 0) {
         return false;
     }
+    /*
+     * ── D53: BUY-NOW MUST CLEAR THE RESERVE ─────────────────────────────────
+     *
+     * 🛑 This function consulted end state, sold state and the standing bid —
+     * and never `reservePrice`, which was enforced in ONE place:
+     * `auctionSettlement`, i.e. only on the competitive path. So a Buy-Now
+     * priced below the reserve completed, and the seller was bound to a price
+     * the reserve existed to refuse.
+     *
+     * The reserve is the seller's floor for the ITEM, not for a particular sale
+     * mechanism. A buyout that undercuts it defeats it entirely — and does so on
+     * the path with no competing bidders to push the price up, which is the one
+     * where the floor matters most.
+     *
+     * 🛑 Checked here rather than at the call site, deliberately: this is the
+     * gate `placeBuyNow` already consults AND the predicate the UI uses to
+     * decide whether to render the button at all, so one change closes the
+     * exploit and stops offering a control that must then refuse.
+     *
+     * Absent/zero/non-finite reserve means NO reserve — which is the common case
+     * and must stay permissive, or every reserve-less auction would lose its
+     * Buy-Now.
+     */
+    if (typeof reservePrice === "number" &&
+        Number.isFinite(reservePrice) &&
+        reservePrice > 0 &&
+        buyNowPrice < reservePrice) {
+        return false;
+    }
     return buyNowPrice > (currentBid ?? 0);
 }
 /**

package/dist/_internal/shared/features/brands/schema.d.ts

@@ -9,26 +9,47 @@ export declare const brandInputSchema: z.ZodObject<{
     founded: z.ZodOptional<z.ZodNumber>;
     isActive: z.ZodDefault<z.ZodBoolean>;
     displayOrder: z.ZodDefault<z.ZodNumber>;
+    highlights: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    faqs: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        question: z.ZodString;
+        answer: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        question: string;
+        answer: string;
+    }, {
+        question: string;
+        answer: string;
+    }>, "many">>;
 }, "strip", z.ZodTypeAny, {
     name: string;
     slug: string;
     isActive: boolean;
     displayOrder: number;
     country?: string | undefined;
+    faqs?: {
+        question: string;
+        answer: string;
+    }[] | undefined;
     description?: string | undefined;
     logoURL?: string | undefined;
     website?: string | undefined;
     founded?: number | undefined;
+    highlights?: string[] | undefined;
 }, {
     name: string;
     slug: string;
     country?: string | undefined;
+    faqs?: {
+        question: string;
+        answer: string;
+    }[] | undefined;
     description?: string | undefined;
     isActive?: boolean | undefined;
     displayOrder?: number | undefined;
     logoURL?: string | undefined;
     website?: string | undefined;
     founded?: number | undefined;
+    highlights?: string[] | undefined;
 }>;
 export declare const brandUpdateSchema: z.ZodObject<Omit<{
     name: z.ZodOptional<z.ZodString>;
@@ -40,24 +61,45 @@ export declare const brandUpdateSchema: z.ZodObject<Omit<{
     founded: z.ZodOptional<z.ZodOptional<z.ZodNumber>>;
     isActive: z.ZodOptional<z.ZodDefault<z.ZodBoolean>>;
     displayOrder: z.ZodOptional<z.ZodDefault<z.ZodNumber>>;
+    highlights: z.ZodOptional<z.ZodOptional<z.ZodArray<z.ZodString, "many">>>;
+    faqs: z.ZodOptional<z.ZodOptional<z.ZodArray<z.ZodObject<{
+        question: z.ZodString;
+        answer: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        question: string;
+        answer: string;
+    }, {
+        question: string;
+        answer: string;
+    }>, "many">>>;
 }, "slug">, "strip", z.ZodTypeAny, {
     country?: string | undefined;
     name?: string | undefined;
+    faqs?: {
+        question: string;
+        answer: string;
+    }[] | undefined;
     description?: string | undefined;
     isActive?: boolean | undefined;
     displayOrder?: number | undefined;
     logoURL?: string | undefined;
     website?: string | undefined;
     founded?: number | undefined;
+    highlights?: string[] | undefined;
 }, {
     country?: string | undefined;
     name?: string | undefined;
+    faqs?: {
+        question: string;
+        answer: string;
+    }[] | undefined;
     description?: string | undefined;
     isActive?: boolean | undefined;
     displayOrder?: number | undefined;
     logoURL?: string | undefined;
     website?: string | undefined;
     founded?: number | undefined;
+    highlights?: string[] | undefined;
 }>;
 export type BrandInput = z.infer<typeof brandInputSchema>;
 export type BrandUpdate = z.infer<typeof brandUpdateSchema>;

package/dist/_internal/shared/features/brands/schema.js

@@ -12,5 +12,23 @@ export const brandInputSchema = z.object({
     founded: z.number().int().min(1800).max(new Date().getFullYear()).optional(),
     isActive: z.boolean().default(true),
     displayOrder: z.number().int().min(0).default(0),
+    /*
+     * Editorial content, rendered by `CategoryHighlightsAndFaqSection` on the
+     * brand page and previously unauthorable — the form did not carry them, so
+     * this schema did not need them either.
+     *
+     * 🛑 CAPPED, both of them. These render in a fixed block above the fold on
+     * a public page, and an unbounded list is how a form becomes a way to break
+     * the page it feeds. The numbers match what the category editor already
+     * enforces for the same two fields on the same renderer.
+     */
+    highlights: z.array(z.string().min(1).max(200)).max(8).optional(),
+    faqs: z
+        .array(z.object({
+        question: z.string().min(1).max(300),
+        answer: z.string().min(1).max(2000),
+    }))
+        .max(8)
+        .optional(),
 });
 export const brandUpdateSchema = brandInputSchema.partial().omit({ slug: true });

package/dist/_internal/shared/features/orders/refund-copy.d.ts

@@ -40,6 +40,28 @@ export declare const REFUND_COPY: {
     readonly siblingPayments: {
         readonly heading: (count: number) => string;
     };
+    /**
+     * What to tell the buyer about the money, immediately after they cancel.
+     *
+     * 🛑 Here rather than inline in the route, because there are two cancel
+     * endpoints plus the buyer's cancel page, and three copies of "we owe you
+     * ₹X" is how a refund timeline comes to be published three different ways
+     * (D20/D31). It is a function of the OUTCOME, so the sentence cannot
+     * disagree with what actually happened — which is the specific failure D14
+     * was: the page said one thing and the money did another.
+     *
+     * 🛑 It deliberately quotes **no timeline**. "5–7 business days" is published
+     * in three contradicting places already and reconciling them is Phase 9; a
+     * fourth statement of it here would be a new owner of a number that needs
+     * fewer, not more.
+     */
+    readonly cancellation: {
+        readonly message: (outcome: {
+            moved: "none" | "gateway" | "owed";
+            amount: number;
+            why?: string;
+        }) => string;
+    };
     readonly shipping: {
         readonly noOptions: "No shipping options available for this item.";
         readonly freeLabel: "Free";

package/dist/_internal/shared/features/orders/refund-copy.js

@@ -44,6 +44,40 @@ export const REFUND_COPY = {
     siblingPayments: {
         heading: (count) => `Other orders from this payment (${count})`,
     },
+    /**
+     * What to tell the buyer about the money, immediately after they cancel.
+     *
+     * 🛑 Here rather than inline in the route, because there are two cancel
+     * endpoints plus the buyer's cancel page, and three copies of "we owe you
+     * ₹X" is how a refund timeline comes to be published three different ways
+     * (D20/D31). It is a function of the OUTCOME, so the sentence cannot
+     * disagree with what actually happened — which is the specific failure D14
+     * was: the page said one thing and the money did another.
+     *
+     * 🛑 It deliberately quotes **no timeline**. "5–7 business days" is published
+     * in three contradicting places already and reconciling them is Phase 9; a
+     * fourth statement of it here would be a new owner of a number that needs
+     * fewer, not more.
+     */
+    cancellation: {
+        message: (outcome) => {
+            if (outcome.moved === "gateway") {
+                return `Order cancelled. A refund of ₹${outcome.amount.toFixed(2)} has been sent back to your original payment method.`;
+            }
+            if (outcome.moved === "owed") {
+                return `Order cancelled. We owe you ₹${outcome.amount.toFixed(2)} — it needs to be sent manually, and our team has been notified.`;
+            }
+            /*
+             * `none` splits two very different situations and must not blur them: an
+             * unpaid order has nothing to refund, while an already-refunded one has
+             * had its money returned. Telling the second buyer "no payment was
+             * taken" would read as a denial that they ever paid.
+             */
+            return outcome.why === "nothing-refundable"
+                ? "Order cancelled. Its payment had already been refunded in full, so nothing further is owed."
+                : "Order cancelled. No payment had been taken, so there is nothing to refund.";
+        },
+    },
     shipping: {
         noOptions: "No shipping options available for this item.",
         freeLabel: "Free",

package/dist/_internal/shared/features/print/label-profiles.d.ts

@@ -0,0 +1,198 @@
+import { MM_PER_INCH, type PrintPageSize } from "../sticker-trace/export/page-sizes";
+/**
+ * CODE128 module width at which essentially every handheld scanner reads
+ * reliably, including cheap CCD units at an angle. 0.25 mm ≈ 10 mil.
+ */
+export declare 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 declare 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 declare function code128WidthMm(characters: number, moduleMm?: number): number;
+/**
+ * An A4 sheet of die-cut labels: where the first one starts and how far apart
+ * they are. `null` on a thermal profile, where the page IS the label.
+ *
+ * 🛑 PITCH, NOT GAP. Pitch is centre-to-centre and is what positions label
+ * number 40; a gap has to be added to a width to get there, and any rounding in
+ * the width then accumulates down the column. Avery publish pitch for the same
+ * reason.
+ */
+export interface SheetLayout {
+    readonly columns: number;
+    readonly rows: number;
+    /** Distance from the page's left edge to the first label's left edge. */
+    readonly marginLeftMm: number;
+    /** Distance from the page's top edge to the first label's top edge. */
+    readonly marginTopMm: number;
+    /** Centre-to-centre horizontal spacing. */
+    readonly pitchXMm: number;
+    /** Centre-to-centre vertical spacing. */
+    readonly pitchYMm: number;
+}
+export type LabelProfileId = "thermal-50x25" | "thermal-38x25" | "thermal-100x50" | "a4-65up" | "a4-24up" | "a4-8up";
+export interface LabelProfile {
+    readonly id: LabelProfileId;
+    readonly label: string;
+    /** One label's die-cut size. */
+    readonly widthMm: number;
+    readonly heightMm: number;
+    /** Printable inset inside the label. */
+    readonly paddingMm: number;
+    /** The page the printer is fed. For thermal, the page is one label. */
+    readonly page: {
+        readonly widthMm: number;
+        readonly heightMm: number;
+    };
+    /** Null for thermal — a roll has no grid. */
+    readonly sheet: SheetLayout | null;
+    readonly isThermal: boolean;
+}
+export declare const LABEL_PROFILES: Readonly<Record<LabelProfileId, LabelProfile>>;
+/** Thermal first — it is what the warehouse actually uses day to day. */
+export declare const LABEL_PROFILE_IDS: readonly LabelProfileId[];
+export declare function labelProfileById(id: LabelProfileId): LabelProfile;
+/**
+ * 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 declare function labelPageCss(profile: LabelProfile): string;
+/**
+ * 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 declare function documentPageCss(page?: {
+    widthMm: number;
+    heightMm: number;
+}, marginMm?: number): string;
+export interface LabelFitReport {
+    readonly fits: boolean;
+    /** Width the symbol needs at `SAFE_MODULE_MM`, quiet zones included. */
+    readonly requiredMm: number;
+    /** Width the label actually offers once padding is removed. */
+    readonly availableMm: number;
+    /**
+     * The module width this stock would force. Compare against
+     * `MIN_SCANNABLE_MODULE_MM` — below it the symbol is unreliable rather than
+     * merely small.
+     */
+    readonly impliedModuleMm: number;
+    /** Plain-language reason, safe to show an operator verbatim. */
+    readonly reason: string;
+}
+/**
+ * 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 declare function labelFitsProfile(profile: LabelProfile, characters: number): LabelFitReport;
+/**
+ * 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 declare function sheetPositionMm(sheet: SheetLayout, index: number): {
+    leftMm: number;
+    topMm: number;
+} | null;
+/**
+ * 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 declare function sheetOverflowMm(profile: LabelProfile): {
+    rightMm: number;
+    bottomMm: number;
+} | null;
+/** Re-exported so a caller converting a legacy inch figure need not hunt. */
+export { MM_PER_INCH };
+export type { PrintPageSize };