@mohasinac/appkit 4.61.0 → 4.62.1

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

@@ -13,8 +13,69 @@ export declare class JobsRepository extends BaseRepository<JobDocument> {
     markDone(id: string, result: JobResult): Promise<JobDocument>;
     markFailed(id: string, error: string): Promise<JobDocument>;
     /**
-     * Refs for finished (done/failed) jobs older than `ttlDays` — used by the
+     * Attempts exhausted, or a permanent failure. The dead-letter state
+     * (Phase 8).
+     *
+     * 🛑 Distinct from `markFailed`, which now means "this attempt failed and a
+     * retry is scheduled". Before Phase 8 there was only `failed`, and it was
+     * terminal with no signal — so a job that gave up looked exactly like a job
+     * that had just failed once, and nothing anywhere distinguished them.
+     */
+    markDead(id: string, error: string): Promise<JobDocument>;
+    /**
+     * Schedule the next attempt as a NEW document (Phase 8).
+     *
+     * ## 🛑 Why a new document and not a reset of this one
+     *
+     * `onJobCreated` fires on CREATE. Flipping a job back to `pending` would
+     * never wake the trigger, so it would sit `pending` forever looking
+     * scheduled — a stall that reads as a queue. A fresh document is what makes
+     * the retry visible to the only mechanism that can run it.
+     *
+     * It also keeps the history: three attempts are three documents, each with
+     * its own error, so a repeating failure is legible instead of being
+     * overwritten by the last one.
+     *
+     * `parentJobId` points at the ORIGINAL — `parentJobId ?? id`, so attempt 3
+     * is linked to attempt 1 rather than to attempt 2. A flat fan means "every
+     * attempt of this job" is one equality query, where a linked list needs N
+     * reads to walk.
+     */
+    createRetry(id: string, job: JobDocument, next: {
+        attempt: number;
+        maxAttempts: number;
+        nextAttemptAt: Date;
+    }): Promise<string>;
+    /**
+     * Retries whose `nextAttemptAt` has passed — the sweep's only query.
+     *
+     * 🛑 `status == pending` AND `nextAttemptAt <= now`, so it can never pick up
+     * a FIRST attempt: an original job carries no `nextAttemptAt`, and a
+     * Firestore inequality excludes every document that lacks the field. That
+     * exclusion is usually the trap (see `.where("isTestData","!=",true)` in
+     * CLAUDE.md, and D26's `orderBy` on an optional field); here it is exactly
+     * the filter wanted, and it is written down so nobody "fixes" it by adding
+     * a default.
+     *
+     * Bounded at 20 per tick. The sweep rides `paymentWindowTimeout`, which runs
+     * every 5 minutes, so that is 240 retries an hour — far above any real
+     * backlog, and low enough that a pathological queue cannot exhaust the
+     * function's own budget in one pass.
+     */
+    getDueRetries(limit?: number): Promise<Array<{
+        id: string;
+        data: JobDocument;
+    }>>;
+    /**
+     * Refs for finished jobs older than `ttlDays` — used by the
      * `cleanupRtdbEvents` sweep to prune the `jobs` collection.
+     *
+     * 🛑 `DEAD` is deliberately NOT in this list. A dead job has an open
+     * `dead_job` case pointing at it, and the job document holds the payload
+     * that would let someone re-run the work by hand — pruning it would leave a
+     * case referencing nothing, which is worse than a stale row. They are
+     * retained until a human resolves the case and can be pruned by a separate,
+     * case-aware sweep if they ever accumulate.
      */
     getStaleFinishedRefs(ttlDays?: number): Promise<DocumentReference[]>;
 }

package/dist/features/jobs/repository/jobs.repository.js

@@ -31,8 +31,91 @@ export class JobsRepository extends BaseRepository {
         });
     }
     /**
-     * Refs for finished (done/failed) jobs older than `ttlDays` — used by the
+     * Attempts exhausted, or a permanent failure. The dead-letter state
+     * (Phase 8).
+     *
+     * 🛑 Distinct from `markFailed`, which now means "this attempt failed and a
+     * retry is scheduled". Before Phase 8 there was only `failed`, and it was
+     * terminal with no signal — so a job that gave up looked exactly like a job
+     * that had just failed once, and nothing anywhere distinguished them.
+     */
+    markDead(id, error) {
+        return this.update(id, {
+            status: JobStatusValues.DEAD,
+            error,
+            finishedAt: new Date(),
+        });
+    }
+    /**
+     * Schedule the next attempt as a NEW document (Phase 8).
+     *
+     * ## 🛑 Why a new document and not a reset of this one
+     *
+     * `onJobCreated` fires on CREATE. Flipping a job back to `pending` would
+     * never wake the trigger, so it would sit `pending` forever looking
+     * scheduled — a stall that reads as a queue. A fresh document is what makes
+     * the retry visible to the only mechanism that can run it.
+     *
+     * It also keeps the history: three attempts are three documents, each with
+     * its own error, so a repeating failure is legible instead of being
+     * overwritten by the last one.
+     *
+     * `parentJobId` points at the ORIGINAL — `parentJobId ?? id`, so attempt 3
+     * is linked to attempt 1 rather than to attempt 2. A flat fan means "every
+     * attempt of this job" is one equality query, where a linked list needs N
+     * reads to walk.
+     */
+    async createRetry(id, job, next) {
+        const created = await this.create({
+            jobType: job.jobType,
+            status: JobStatusValues.PENDING,
+            payload: job.payload,
+            requestedBy: job.requestedBy,
+            attempt: next.attempt,
+            maxAttempts: next.maxAttempts,
+            nextAttemptAt: next.nextAttemptAt,
+            parentJobId: job.parentJobId ?? id,
+            lastError: job.error,
+        });
+        return created.id;
+    }
+    /**
+     * Retries whose `nextAttemptAt` has passed — the sweep's only query.
+     *
+     * 🛑 `status == pending` AND `nextAttemptAt <= now`, so it can never pick up
+     * a FIRST attempt: an original job carries no `nextAttemptAt`, and a
+     * Firestore inequality excludes every document that lacks the field. That
+     * exclusion is usually the trap (see `.where("isTestData","!=",true)` in
+     * CLAUDE.md, and D26's `orderBy` on an optional field); here it is exactly
+     * the filter wanted, and it is written down so nobody "fixes" it by adding
+     * a default.
+     *
+     * Bounded at 20 per tick. The sweep rides `paymentWindowTimeout`, which runs
+     * every 5 minutes, so that is 240 retries an hour — far above any real
+     * backlog, and low enough that a pathological queue cannot exhaust the
+     * function's own budget in one pass.
+     */
+    async getDueRetries(limit = 20) {
+        const snap = await this.getCollection()
+            .where(JOB_FIELDS.STATUS, "==", JobStatusValues.PENDING)
+            .where(JOB_FIELDS.NEXT_ATTEMPT_AT, "<=", new Date())
+            .limit(limit)
+            .get();
+        return snap.docs.map((d) => ({
+            id: d.id,
+            data: { id: d.id, ...d.data() },
+        }));
+    }
+    /**
+     * Refs for finished jobs older than `ttlDays` — used by the
      * `cleanupRtdbEvents` sweep to prune the `jobs` collection.
+     *
+     * 🛑 `DEAD` is deliberately NOT in this list. A dead job has an open
+     * `dead_job` case pointing at it, and the job document holds the payload
+     * that would let someone re-run the work by hand — pruning it would leave a
+     * case referencing nothing, which is worse than a stale row. They are
+     * retained until a human resolves the case and can be pruned by a separate,
+     * case-aware sweep if they ever accumulate.
      */
     async getStaleFinishedRefs(ttlDays = 30) {
         const cutoff = new Date();

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

@@ -23,6 +23,20 @@ export declare const JobStatusValues: {
     readonly PROCESSING: "processing";
     readonly DONE: "done";
     readonly FAILED: "failed";
+    /**
+     * Phase 8 — attempts exhausted. The dead-letter state.
+     *
+     * 🛑 `failed` and `dead` are DIFFERENT facts and conflating them is what
+     * made a failed job terminal with no signal. `failed` now means "this
+     * attempt failed, and a retry is scheduled or the failure was permanent";
+     * `dead` means "we have stopped trying" and is the only one that opens a
+     * case.
+     *
+     * A reader that treats every non-`done` as hopeless loses that distinction —
+     * which is why the retention sweep excludes `dead` while an open case
+     * references it: the row is the evidence.
+     */
+    readonly DEAD: "dead";
 };
 export type JobStatus = (typeof JobStatusValues)[keyof typeof JobStatusValues];
 export interface JobResult {
@@ -52,7 +66,55 @@ export interface JobDocument extends BaseDocument {
     error?: string;
     startedAt?: Date;
     finishedAt?: Date;
+    /**
+     * 1-based. Absent means 1 — every job written before this field is a first
+     * attempt, which is both true and what every reader should assume.
+     */
+    attempt?: number;
+    /** Defaults to `JOB_MAX_ATTEMPTS`; a jobType may lower it. */
+    maxAttempts?: number;
+    /**
+     * When a retry becomes eligible.
+     *
+     * 🛑 A retry is a **NEW DOCUMENT**, not a mutation of this one, because
+     * `onJobCreated` fires on CREATE — re-running a job by flipping its status
+     * back to `pending` would never wake the trigger, and the job would sit
+     * `pending` forever looking scheduled. So this field lives on the NEW
+     * document and a sweep is what moves it from scheduled to running.
+     */
+    nextAttemptAt?: Date;
+    /**
+     * The document this is a retry OF — present on every attempt after the
+     * first, and absent on the original.
+     *
+     * 🛑 Points at the ORIGINAL, not at the immediately previous attempt. A
+     * flat chain means "show me every attempt of this job" is one equality
+     * query, where a linked list would need N reads to walk; and the question
+     * anyone actually asks is "did this job eventually work", which is about the
+     * original.
+     */
+    parentJobId?: string;
+    /** Why this attempt failed, kept per attempt so a pattern is visible. */
+    lastError?: string;
 }
+/**
+ * Attempts before a job is declared dead.
+ *
+ * Three, with `JOB_BACKOFF_MS` below: a transient fault usually clears in
+ * minutes, and a fourth attempt an hour later is far more likely to be the
+ * same permanent fault again than a different outcome.
+ */
+export declare const JOB_MAX_ATTEMPTS = 3;
+/**
+ * Delay before attempt 2 and attempt 3.
+ *
+ * 🛑 Indexed by `attempt - 1`, so the array length must be at least
+ * `JOB_MAX_ATTEMPTS - 1`. The last value is reused if it is shorter, rather
+ * than producing `undefined` — a `nextAttemptAt` of `Invalid Date` would make
+ * the sweep's `<= now` comparison false forever and the retry would never run,
+ * which is the silent-stall shape this whole phase exists to remove.
+ */
+export declare const JOB_BACKOFF_MS: readonly [number, number];
 export declare const JOB_FIELDS: {
     readonly JOB_TYPE: "jobType";
     readonly STATUS: "status";
@@ -63,10 +125,28 @@ export declare const JOB_FIELDS: {
     readonly FINISHED_AT: "finishedAt";
     readonly CREATED_AT: "createdAt";
     readonly UPDATED_AT: "updatedAt";
+    readonly ATTEMPT: "attempt";
+    readonly MAX_ATTEMPTS: "maxAttempts";
+    readonly NEXT_ATTEMPT_AT: "nextAttemptAt";
+    readonly PARENT_JOB_ID: "parentJobId";
     readonly STATUS_VALUES: {
         readonly PENDING: "pending";
         readonly PROCESSING: "processing";
         readonly DONE: "done";
         readonly FAILED: "failed";
+        /**
+         * Phase 8 — attempts exhausted. The dead-letter state.
+         *
+         * 🛑 `failed` and `dead` are DIFFERENT facts and conflating them is what
+         * made a failed job terminal with no signal. `failed` now means "this
+         * attempt failed, and a retry is scheduled or the failure was permanent";
+         * `dead` means "we have stopped trying" and is the only one that opens a
+         * case.
+         *
+         * A reader that treats every non-`done` as hopeless loses that distinction —
+         * which is why the retention sweep excludes `dead` while an open case
+         * references it: the row is the evidence.
+         */
+        readonly DEAD: "dead";
     };
 };

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

@@ -21,7 +21,39 @@ export const JobStatusValues = {
     PROCESSING: "processing",
     DONE: "done",
     FAILED: "failed",
+    /**
+     * Phase 8 — attempts exhausted. The dead-letter state.
+     *
+     * 🛑 `failed` and `dead` are DIFFERENT facts and conflating them is what
+     * made a failed job terminal with no signal. `failed` now means "this
+     * attempt failed, and a retry is scheduled or the failure was permanent";
+     * `dead` means "we have stopped trying" and is the only one that opens a
+     * case.
+     *
+     * A reader that treats every non-`done` as hopeless loses that distinction —
+     * which is why the retention sweep excludes `dead` while an open case
+     * references it: the row is the evidence.
+     */
+    DEAD: "dead",
 };
+/**
+ * Attempts before a job is declared dead.
+ *
+ * Three, with `JOB_BACKOFF_MS` below: a transient fault usually clears in
+ * minutes, and a fourth attempt an hour later is far more likely to be the
+ * same permanent fault again than a different outcome.
+ */
+export const JOB_MAX_ATTEMPTS = 3;
+/**
+ * Delay before attempt 2 and attempt 3.
+ *
+ * 🛑 Indexed by `attempt - 1`, so the array length must be at least
+ * `JOB_MAX_ATTEMPTS - 1`. The last value is reused if it is shorter, rather
+ * than producing `undefined` — a `nextAttemptAt` of `Invalid Date` would make
+ * the sweep's `<= now` comparison false forever and the retry would never run,
+ * which is the silent-stall shape this whole phase exists to remove.
+ */
+export const JOB_BACKOFF_MS = [5 * 60 * 1000, 30 * 60 * 1000];
 export const JOB_FIELDS = {
     JOB_TYPE: "jobType",
     STATUS: "status",
@@ -32,5 +64,10 @@ export const JOB_FIELDS = {
     FINISHED_AT: "finishedAt",
     CREATED_AT: "createdAt",
     UPDATED_AT: "updatedAt",
+    // Phase 8 retry/DLQ. `NEXT_ATTEMPT_AT` is the sweep's query field.
+    ATTEMPT: "attempt",
+    MAX_ATTEMPTS: "maxAttempts",
+    NEXT_ATTEMPT_AT: "nextAttemptAt",
+    PARENT_JOB_ID: "parentJobId",
     STATUS_VALUES: JobStatusValues,
 };

package/dist/features/layout/hooks/useFormBottomActions.js

@@ -3,6 +3,7 @@ import { jsx as _jsx } from "react/jsx-runtime";
 import { useContext, useMemo } from "react";
 import { FormShellContext } from "../../../ui/forms/FormShell.js";
 import { FormErrorList } from "../../../ui/forms/FormErrorList.js";
+import { Div } from "../../../ui/components/Div.js";
 import { useIsInsideOverlay } from "../../../ui/components/overlay-context.js";
 import { useBottomActions } from "./useBottomActions.js";
 /**
@@ -98,7 +99,25 @@ export function useFormBottomActions({ onSubmit, onCancel, submitLabel = "Save",
         infoLabel: showErrors
             ? `Fix ${errorCount} ${errorCount === 1 ? "issue" : "issues"}`
             : undefined,
-        infoPanel: showErrors && ctx ? _jsx(FormErrorList, { ctx: ctx }) : undefined,
+        /*
+         * 🛑 The alert region lives HERE, not in `FormErrorList`.
+         *
+         * Without it a failed submit on a phone announced nothing at all: the
+         * list has no role, `InfoPanel` has no role, and the only signal was the
+         * disclosure button's text changing — which a screen reader does not read
+         * out unprompted. This is the whole error surface on mobile, since
+         * `useBottomActions` defaults to `desktop: "hidden"`.
+         *
+         * It cannot go on `FormErrorList` itself: the list's other consumer is
+         * `<FormErrorSummary>`, whose wrapper is already `role="alert"`, and
+         * nesting one alert region inside another makes the announcement
+         * ambiguous and duplicated.
+         *
+         * `aria-live="polite"` rather than `role="alert"`'s implicit assertive —
+         * the user has just pressed Save and is expecting a response, so there is
+         * nothing to interrupt. Same choice `FormErrorSummary` makes.
+         */
+        infoPanel: showErrors && ctx ? (_jsx(Div, { role: "alert", "aria-live": "polite", children: _jsx(FormErrorList, { ctx: ctx }) })) : undefined,
         // Bumped by every submit attempt, so a second failed Save re-opens a
         // sheet the user collapsed — while an ordinary re-render does not.
         infoOpenSignal: showErrors ? ctx?.submitAttemptCount : undefined,

package/dist/features/lottery/schemas/zod.d.ts

@@ -42,12 +42,12 @@ export declare const reopenLotterySlotSchema: z.ZodObject<{
     adminUserId: z.ZodString;
 }, "strip", z.ZodTypeAny, {
     slotNumber: number;
-    sourceType: "event" | "product";
+    sourceType: "product" | "event";
     sourceId: string;
     adminUserId: string;
 }, {
     slotNumber: number;
-    sourceType: "event" | "product";
+    sourceType: "product" | "event";
     sourceId: string;
     adminUserId: string;
 }>;
@@ -68,7 +68,7 @@ export declare const submitLotteryPullSchema: z.ZodEffects<z.ZodObject<{
 }, "strip", z.ZodTypeAny, {
     userId: string;
     transactionId: string;
-    sourceType: "event" | "product";
+    sourceType: "product" | "event";
     paymentTime: string;
     purchasedItemNumber: number;
     userPhone: string;
@@ -79,7 +79,7 @@ export declare const submitLotteryPullSchema: z.ZodEffects<z.ZodObject<{
 }, {
     userId: string;
     transactionId: string;
-    sourceType: "event" | "product";
+    sourceType: "product" | "event";
     paymentTime: string;
     purchasedItemNumber: number;
     userPhone: string;
@@ -90,7 +90,7 @@ export declare const submitLotteryPullSchema: z.ZodEffects<z.ZodObject<{
 }>, {
     userId: string;
     transactionId: string;
-    sourceType: "event" | "product";
+    sourceType: "product" | "event";
     paymentTime: string;
     purchasedItemNumber: number;
     userPhone: string;
@@ -101,7 +101,7 @@ export declare const submitLotteryPullSchema: z.ZodEffects<z.ZodObject<{
 }, {
     userId: string;
     transactionId: string;
-    sourceType: "event" | "product";
+    sourceType: "product" | "event";
     paymentTime: string;
     purchasedItemNumber: number;
     userPhone: string;

package/dist/features/media/MediaImage.js

@@ -113,8 +113,29 @@ export function MediaImage({ src, alt, size = "card", priority = false, loading,
      * the placeholder, the `<picture>` and the plain `<Image>` cannot disagree
      * about their dimensions — a fallback that occupies a different box from the
      * image it replaces makes a grid jump as things load.
+     *
+     * 🛑 `max-h-full` IS THE OTHER HALF OF SIZE_BOX, added 2026-10-23. SIZE_BOX
+     * alone fixed the auto-height parent and broke the ALREADY-SIZED one: a
+     * parent that is 320x128 got a 320x320 box, so `overflow-hidden` cropped it
+     * to the top 40% of a letterboxed square. Measured 89 of 143 call sites in
+     * that shape — every image preview on the review, document and site-settings
+     * surfaces. `max-height:100%` resolves to `none` against an auto-height
+     * parent, so it clamps ONLY in the broken case.
+     *
+     * Measured in a browser (box for each parent shape), not argued:
+     *
+     *   parent               w-full aspect  +max-h-full   +h-full
+     *   320x128 definite     320x320  ✗     320x128  ✓    320x128 ✓
+     *   h128, width shrink   320x320  ✗     320x128  ✓    320x128 ✓
+     *   width 200, h AUTO    200x200  ✓     200x200  ✓    200x784 ✗
+     *   64px thumb stretched
+     *     by a flex row       64x64   ✓      64x64   ✓     64x90  ✗
+     *
+     * So `h-full` is NOT the fix — it wins over `aspect-ratio` whenever the
+     * parent's height is definite, including the height a flex/grid row hands a
+     * thumbnail by stretching it. That is why this is a MAX and not a height.
      */
-    const boxClass = fill ? "h-full" : SIZE_BOX[size];
+    const boxClass = fill ? "h-full" : `${SIZE_BOX[size]} max-h-full`;
     // Reset error/load/retry state whenever the resolved src actually changes.
     // Without this, a component instance that hit a load failure once (e.g.
     // lost the post-upload propagation race above) latches hasError forever,

package/dist/features/media/upload/ImageUpload.js

@@ -222,7 +222,7 @@ accept = IMAGE_ACCEPT_ATTR, maxSizeMB = MAX_IMAGE_BYTES / MEGABYTE, label = "Upl
             fileInputRef.current.value = "";
         onChange?.("");
     };
-    return (_jsxs(Stack, { gap: "3", children: [label && (_jsx(Label, { className: "block", color: "muted", size: "sm", weight: "medium", children: label })), _jsx(Div, { className: "relative", children: preview ? (_jsxs(Stack, { gap: "sm", children: [_jsxs(Div, { className: `relative h-32 max-w-xs mx-auto ${__O.hidden}`, rounded: "lg", border: "default", children: [_jsx(MediaImage, { src: preview, alt: "Preview", size: "card" }), uploading && progress > 0 && (_jsx(Div, { className: "absolute inset-x-0 bottom-0", children: _jsx(Progress, { value: progress, size: "sm" }) }))] }), !uploading && (_jsxs(Row, { wrap: true, gap: "sm", children: [(enableCrop || enableAdvancedCrop) && (_jsx(Button, { type: "button", onClick: () => openEditor(preview), variant: "secondary", size: "sm", children: tMediaEditor("editImage") })), _jsx(Button, { type: "button", onClick: () => fileInputRef.current?.click(), variant: "outline", size: "sm", children: tUpload("change") }), _jsx(Button, { type: "button", onClick: handleRemove, variant: "danger", size: "sm", children: tUpload("remove") })] }))] })) : (_jsxs(_Fragment, { children: [showCamera && isCameraSupported && (_jsx(CameraCapture, { mode: "photo", facingMode: "environment", onCapture: handleCameraCapture, onError: setError })), !showCamera && (_jsxs(Stack, { gap: "sm", children: [_jsxs(Row, { gap: "sm", wrap: true, children: [showFileInput && (_jsx(Button, { type: "button", onClick: () => fileInputRef.current?.click(), disabled: uploading, variant: "outline", size: "sm", children: uploading ? tUpload("uploading") : tUpload("clickToUpload") })), captureSource !== "file-only" && isCameraSupported && (_jsx(Button, { type: "button", onClick: () => setCaptureMode("camera"), disabled: uploading, variant: "ghost", size: "sm", children: t("switchToCamera") })), captureSource !== "file-only" && !isCameraSupported && (_jsx(Button, { type: "button", onClick: () => mobileCaptureRef.current?.click(), disabled: uploading, variant: "ghost", size: "sm", children: t("switchToCamera") }))] }), _jsxs(Text, { size: "xs", variant: "secondary", children: [accept === "image/*"
+    return (_jsxs(Stack, { gap: "3", children: [label && (_jsx(Label, { className: "block", color: "muted", size: "sm", weight: "medium", children: label })), _jsx(Div, { className: "relative", children: preview ? (_jsxs(Stack, { gap: "sm", children: [_jsxs(Div, { className: `relative w-full h-32 max-w-xs mx-auto ${__O.hidden}`, rounded: "lg", border: "default", children: [_jsx(MediaImage, { src: preview, alt: "Preview", size: "card" }), uploading && progress > 0 && (_jsx(Div, { className: "absolute inset-x-0 bottom-0", children: _jsx(Progress, { value: progress, size: "sm" }) }))] }), !uploading && (_jsxs(Row, { wrap: true, gap: "sm", children: [(enableCrop || enableAdvancedCrop) && (_jsx(Button, { type: "button", onClick: () => openEditor(preview), variant: "secondary", size: "sm", children: tMediaEditor("editImage") })), _jsx(Button, { type: "button", onClick: () => fileInputRef.current?.click(), variant: "outline", size: "sm", children: tUpload("change") }), _jsx(Button, { type: "button", onClick: handleRemove, variant: "danger", size: "sm", children: tUpload("remove") })] }))] })) : (_jsxs(_Fragment, { children: [showCamera && isCameraSupported && (_jsx(CameraCapture, { mode: "photo", facingMode: "environment", onCapture: handleCameraCapture, onError: setError })), !showCamera && (_jsxs(Stack, { gap: "sm", children: [_jsxs(Row, { gap: "sm", wrap: true, children: [showFileInput && (_jsx(Button, { type: "button", onClick: () => fileInputRef.current?.click(), disabled: uploading, variant: "outline", size: "sm", children: uploading ? tUpload("uploading") : tUpload("clickToUpload") })), captureSource !== "file-only" && isCameraSupported && (_jsx(Button, { type: "button", onClick: () => setCaptureMode("camera"), disabled: uploading, variant: "ghost", size: "sm", children: t("switchToCamera") })), captureSource !== "file-only" && !isCameraSupported && (_jsx(Button, { type: "button", onClick: () => mobileCaptureRef.current?.click(), disabled: uploading, variant: "ghost", size: "sm", children: t("switchToCamera") }))] }), _jsxs(Text, { size: "xs", variant: "secondary", children: [accept === "image/*"
                                             ? `JPG PNG GIF WebP`
                                             : accept.split(",").map((a) => a.split("/")[1]?.toUpperCase() ?? a).join(" "), " ", "\u2014 max ", maxSizeMB, "MB"] })] }))] })) }), _jsx("input", { ref: fileInputRef, type: "file", accept: accept, onChange: handleFileChange, className: "hidden", "aria-hidden": "true", "data-testid": "media-upload-input" }), showCamera && !isCameraSupported && (_jsx("input", { ref: mobileCaptureRef, type: "file", accept: IMAGE_ACCEPT_ATTR, capture: "environment", onChange: handleFileChange, className: "hidden", "aria-hidden": "true", "data-testid": "media-upload-capture-input" })), helperText && !error && (_jsx(Text, { variant: "secondary", size: "xs", children: helperText })), error && _jsx(Alert, { variant: "error", children: error }), uploading && (_jsxs(Row, { gap: "sm", children: [_jsx(Spinner, { size: "sm" }), _jsx(Text, { size: "sm", variant: "secondary", children: tUpload("uploadingProgress", { progress }) })] })), cropPreviewUrl && !enableAdvancedCrop && (_jsx(ImageCropModal, { isOpen: showCropModal, imageUrl: cropPreviewUrl, onClose: handleCropClose, onSave: handleCropSave })), cropPreviewUrl && enableAdvancedCrop && (_jsx(ImageEditor, { isOpen: showAdvancedEditor, imageUrl: cropPreviewUrl, onClose: handleAdvancedEditorClose, onSave: handleAdvancedEditorSave, aspectRatio: cropAspectRatio }))] }));
 }

package/dist/features/obligations/constants/policies.js

@@ -37,6 +37,7 @@
 import { ORDER_RETURN_WINDOW_DAYS, ORDER_AUTO_CONFIRM_DAYS, } from "../../../_internal/shared/features/orders/config.js";
 import { PROTECTION_CLAIM_WINDOW_HOURS } from "../../../_internal/shared/features/shipping/protections.js";
 import { PAYMENT_WINDOW_MINUTES } from "../../orders/constants/payment-window.js";
+import { hasOpenCourierBlock } from "../../orders/utils/courier-block.js";
 const isPaid = (o) => o.paymentStatus === "paid";
 const notTerminal = (o) => o.status !== "cancelled" && o.status !== "refunded";
 /**
@@ -87,7 +88,29 @@ export const OBLIGATION_POLICIES = {
         anchor: (o) => o.acceptedAt,
         duration: { value: 2, unit: "days", calendar: "business" },
         warnAt: [{ value: 8, unit: "hours", calendar: "calendar" }],
-        precondition: (o) => isPaid(o) && notTerminal(o) && !hasDispatched(o),
+        /*
+         * 🛑 `!hasOpenCourierBlock(o)` — DO NOT REMOVE, and do not "simplify" it
+         * into the stored field.
+         *
+         * This is `onDue: "act"`, so firing cancels the order and refunds the
+         * buyer with the seller recorded as having failed to dispatch. When the
+         * platform's own courier wallet is empty, nothing the seller can do makes
+         * the booking succeed — so without this guard our funding state cancels a
+         * paid order and blames them for it.
+         *
+         * The engine re-evaluates `precondition` at fire time and closes
+         * `superseded` when it returns false, so the clock PAUSES while blocked and
+         * resumes when the block clears. No new mechanism, no stored timer.
+         *
+         * 🛑 This is the ONLY `onDue: "act"` policy that needs the guard, and the
+         * others were checked rather than assumed: `hasDispatched` is
+         * `Boolean(o.shippingDate)`, so `delivery-confirm` (which REQUIRES
+         * `hasDispatched`) and everything post-delivery can never fire on an order
+         * that was never booked. `seller-accept` requires `!o.acceptedAt`, and a
+         * booking is only attempted after acceptance. Adding the guard there too
+         * would be redundant and would imply nobody traced it.
+         */
+        precondition: (o) => isPaid(o) && notTerminal(o) && !hasDispatched(o) && !hasOpenCourierBlock(o),
         blockedBy: ["seller-accept"],
         onDue: "act",
         publishedCopyKey: "obligations.sellerDispatch",

package/dist/features/orders/components/EmiInstallmentsPanel.js

@@ -4,6 +4,7 @@ import { useState } from "react";
 import { Badge, Button, Div, Form, Row, Stack, Text, useToast } from "../../../ui/index.js";
 import { FieldInput } from "../../../ui/forms/index.js";
 import { formatCurrency } from "../../../utils/number.formatter.js";
+import { toUserMessage } from "../../../errors/error-display-map.js";
 import { normalizeError } from "../../../errors/normalize.js";
 function stateOf(i) {
     if (i.status === "paid")
@@ -28,19 +29,34 @@ export function EmiInstallmentsPanel({ orderId, installments, remainingBalance,
     const money = (value) => formatCurrency(value, currency);
     const ordered = [...installments].sort((a, b) => a.index - b.index);
     const outstanding = ordered.filter((i) => i.status !== "paid").length;
-    const submit = async (index) => {
+    /*
+     * Takes `setFieldError` from the <Form> render prop rather than closing
+     * over state, because the failure belongs ON the reference field.
+     *
+     * This panel used to be toast-only AND gate submission by disabling the
+     * button on an empty reference — so an incomplete form could not be sent
+     * and said nothing about why, and a rejected reference produced a toast
+     * that was gone before the buyer looked back at the input. Both are money
+     * surfaces on somebody's order.
+     */
+    const submit = async (index, fieldName, setFieldError) => {
+        const trimmed = reference.trim();
+        if (trimmed.length === 0) {
+            setFieldError(fieldName, "Enter the UTR or reference number from your transfer.");
+            return;
+        }
         setIsSubmitting(true);
         try {
-            await onSubmit({ installmentIndex: index, transactionId: reference.trim() });
+            await onSubmit({ installmentIndex: index, transactionId: trimmed });
             showToast("Payment reference submitted — the seller will confirm it.", "success");
             setOpenIndex(null);
             setReference("");
         }
         catch (err) {
-            void normalizeError(err);
-            // The action's own message is surfaced by the caller's error mapping;
-            // this only has to stop the panel pretending the submission landed.
-            showToast("Couldn't submit that payment. Please try again.", "error");
+            const normalized = normalizeError(err);
+            setFieldError(fieldName, toUserMessage(normalized.code, undefined, {
+                fallback: "Couldn't submit that payment reference. Please try again.",
+            }));
         }
         finally {
             setIsSubmitting(false);
@@ -49,9 +65,11 @@ export function EmiInstallmentsPanel({ orderId, installments, remainingBalance,
     return (_jsx(Div, { surface: "card", border: "default", rounded: "lg", padding: "md", children: _jsxs(Stack, { gap: "sm", children: [_jsxs(Row, { align: "center", justify: "between", gap: "sm", children: [_jsx(Text, { weight: "semibold", children: "Your EMI plan" }), remainingBalance !== undefined && remainingBalance > 0 && (_jsxs(Text, { size: "sm", color: "muted", children: [money(remainingBalance), " outstanding across ", outstanding, " instalment", outstanding === 1 ? "" : "s"] }))] }), _jsx(Text, { size: "xs", color: "muted", children: "You can pay any instalment whenever you like, including ahead of its due date \u2014 paying early settles the plan sooner and does not cost more." }), _jsx(Stack, { gap: "xs", children: ordered.map((inst) => {
                         const state = stateOf(inst);
                         const due = inst.dueDate ? new Date(inst.dueDate) : null;
+                        // Per-installment, so each open row's error is keyed to its own field.
+                        const fieldName = `emi-reference-${orderId}-${inst.index}`;
                         return (_jsxs(Div, { border: "default", rounded: "md", padding: "sm", children: [_jsxs(Row, { align: "center", justify: "between", gap: "sm", className: "min-w-0", children: [_jsxs(Stack, { gap: "xs", className: "min-w-0", children: [_jsxs(Text, { size: "sm", weight: "medium", children: ["Instalment ", inst.index, " \u00B7 ", money(inst.amount)] }), _jsx(Text, { size: "xs", color: "muted", children: due ? `Due ${due.toLocaleDateString()}` : "No due date recorded" })] }), _jsxs(Row, { align: "center", gap: "xs", className: "flex-shrink-0", children: [_jsx(Badge, { variant: state === "paid" ? "success" : state === "awaiting-review" ? "warning" : "default", children: STATE_LABEL[state] }), state === "payable" && (_jsx(Button, { type: "button", size: "sm", variant: "secondary", onClick: () => {
                                                         setOpenIndex(openIndex === inst.index ? null : inst.index);
                                                         setReference("");
-                                                    }, children: openIndex === inst.index ? "Cancel" : "Pay now" }))] })] }), openIndex === inst.index && (_jsx(Div, { className: "mt-3", children: _jsx(Form, { onSubmit: (e) => e.preventDefault(), children: () => (_jsxs(Stack, { gap: "sm", children: [_jsxs(Text, { size: "xs", color: "muted", children: ["Transfer ", money(inst.amount), " to the seller, then enter the UTR or reference number so they can confirm it."] }), _jsx(FieldInput, { name: `emi-reference-${orderId}-${inst.index}`, label: "UTR / reference number", required: true, value: reference, onChange: setReference }), _jsx(Button, { type: "submit", size: "sm", isLoading: isSubmitting, disabled: reference.trim().length === 0 || isSubmitting, onClick: () => { void submit(inst.index); }, children: "Submit payment reference" })] })) }) }))] }, inst.index));
+                                                    }, children: openIndex === inst.index ? "Cancel" : "Pay now" }))] })] }), openIndex === inst.index && (_jsx(Div, { className: "mt-3", children: _jsx(Form, { onSubmit: (e) => e.preventDefault(), children: ({ setFieldError, clearErrors }) => (_jsxs(Stack, { gap: "sm", children: [_jsxs(Text, { size: "xs", color: "muted", children: ["Transfer ", money(inst.amount), " to the seller, then enter the UTR or reference number so they can confirm it."] }), _jsx(FieldInput, { name: fieldName, label: "UTR / reference number", required: true, value: reference, onChange: (v) => { clearErrors(); setReference(v); } }), _jsx(Button, { type: "submit", size: "sm", isLoading: isSubmitting, disabled: isSubmitting, onClick: () => { void submit(inst.index, fieldName, setFieldError); }, children: "Submit payment reference" })] })) }) }))] }, inst.index));
                     }) })] }) }));
 }

package/dist/features/orders/components/OrderPaymentSummary.js

@@ -32,7 +32,16 @@ function legacyFallback(order) {
         method,
         transactionId: order.paymentTransactionId ?? order.paymentId,
         proofUrl: order.paymentProofUrl,
-        amount: order.totalPrice,
+        /*
+         * 🛑 D46/D47 — `amountDue`, falling back to `totalPrice`. This figure is
+         * what a MANUAL payer is told to transfer and what an admin verifies the
+         * proof against, so on a points-funded order `totalPrice` would ask the
+         * buyer for money the order does not owe — and then the admin would reject
+         * a correct ₹750 UTR for not matching ₹1,000.
+         *
+         * `?? totalPrice`, never `?? 0`: absent means no points were used.
+         */
+        amount: order.amountDue ?? order.totalPrice,
         verificationMethod: method === "cod" ? "cod_collection" : method === "manual" ? "manual_review" : "order_status",
     };
 }

package/dist/features/orders/components/OrderProvenanceCard.d.ts

@@ -0,0 +1,8 @@
+import type { OrderSourceContext } from "../schemas/firestore";
+export interface OrderProvenanceCardProps {
+    sourceContext?: OrderSourceContext;
+    /** Falls back to the configured default currency when omitted. */
+    currency?: string;
+    className?: string;
+}
+export declare function OrderProvenanceCard({ sourceContext, currency, className, }: OrderProvenanceCardProps): import("react").JSX.Element | null;