@mohasinac/appkit 4.62.0 → 4.62.1

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/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;

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

@@ -0,0 +1,185 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * OrderProvenanceCard — renders `OrderDocument.sourceContext`, the record of
+ * HOW the buyer earned the right to buy at this price.
+ *
+ * ## Why this component had to be written
+ *
+ * `sourceContext` is a six-variant discriminated union, assembled at a real
+ * cost — an auction pays one `findByProductSorted`, an offer one `findById` —
+ * written on every order by both checkout paths, mapped through to the client
+ * type by `orderDocumentToOrder` (adapters.ts:359) … and, until this file,
+ * rendered in **zero** `.tsx` files anywhere in the repo.
+ *
+ * That is Root Cause #52/#57: the data was already present and complete, and
+ * no surface was ever wired to present it. The buyer could not see what they
+ * had agreed, the seller could not see what they had accepted, and support
+ * could not see either.
+ *
+ * ## What it deliberately does NOT do
+ *
+ * **`standard` renders nothing.** Its only field is the list price, which the
+ * order total already shows — a card reading "Standard purchase" on every
+ * ordinary order is noise that would teach people to ignore the card on the
+ * orders where it matters. It is still an explicit `case`, so the switch stays
+ * exhaustive.
+ *
+ * **A saving is shown only where it is real.** Not every variant records a
+ * displaced price: `auction-buy-now` has `listPrice`, `offer-accepted` has
+ * `listPriceAtOffer`, and `auction-won` has only `startingBid` — which is a
+ * floor, not an asking price, so presenting the gap as a discount would be a
+ * fabrication. Where a displaced price exists it is shown only when it is
+ * strictly greater than what was paid.
+ *
+ * **Nothing is fetched.** It is handed the context the page already loaded; a
+ * component that fetched would fire one request per opened drawer per portal.
+ */
+import { Badge, Card, DescriptionField, Heading, Row, Stack, Text } from "../../../ui/index.js";
+import { formatCurrency } from "../../../utils/number.formatter.js";
+import { formatDate } from "../../../utils/date.formatter.js";
+/**
+ * A date on a `sourceContext` survives a Firestore round trip as a Timestamp,
+ * an ISO string or a Date depending on which path loaded it, so normalise
+ * rather than assuming. An unparseable value renders an em-dash — never
+ * `new Date()`, which would invent a timestamp for a record that has none
+ * (the rule `OrderStatusTimeline` already follows).
+ */
+function dateText(value) {
+    if (value === null || value === undefined)
+        return "—";
+    const raw = typeof value === "object" && value !== null && "toDate" in value
+        ? value.toDate()
+        : value;
+    const d = raw instanceof Date ? raw : new Date(raw);
+    return Number.isFinite(d.getTime()) ? formatDate(d) : "—";
+}
+function plural(n, one, many) {
+    return `${n} ${n === 1 ? one : many}`;
+}
+function contentFor(ctx, currency) {
+    const money = (n) => formatCurrency(n, currency);
+    switch (ctx.path) {
+        case "standard":
+            // Deliberately silent — see the header. Explicit so the switch is exhaustive.
+            return null;
+        case "auction-won": {
+            const rows = [
+                { label: "Winning bid", value: money(ctx.winningBidAmount) },
+                { label: "Bids in the auction", value: String(ctx.bidCount) },
+                { label: "Starting bid", value: money(ctx.startingBid) },
+            ];
+            if (ctx.runnerUpAmount !== undefined) {
+                rows.push({ label: "Runner-up bid", value: money(ctx.runnerUpAmount) });
+            }
+            if (ctx.reservePrice !== undefined) {
+                rows.push({
+                    label: "Reserve",
+                    value: `${money(ctx.reservePrice)} — ${ctx.reserveMet ? "met" : "not met"}`,
+                });
+            }
+            rows.push({ label: "Auction ended", value: dateText(ctx.auctionEndedAt) });
+            return {
+                title: "Won at auction",
+                tone: "success",
+                summary: ctx.bidCount > 1
+                    ? `Highest of ${plural(ctx.bidCount, "bid", "bids")}.`
+                    : "The only bid placed.",
+                rows,
+            };
+        }
+        case "auction-buy-now": {
+            const rows = [
+                { label: "Buy Now price", value: money(ctx.buyNowPrice) },
+                { label: "List price", value: money(ctx.listPrice) },
+                {
+                    label: "Standing bid beaten",
+                    value: ctx.standingBidAtBuyout > 0 ? money(ctx.standingBidAtBuyout) : "none",
+                },
+                { label: "Bids at buyout", value: String(ctx.bidCount) },
+                { label: "Bought", value: dateText(ctx.boughtAt) },
+            ];
+            return {
+                title: "Bought now, ending the auction",
+                tone: "info",
+                /*
+                 * A buyout IS a real bid (the schema's own note: recording bidCount 0
+                 * would bake a falsehood into an immutable record), so the summary
+                 * must not claim nobody had bid when somebody had.
+                 */
+                summary: ctx.bidCount > 0
+                    ? `Taken at the Buy Now price while ${plural(ctx.bidCount, "bid was", "bids were")} live.`
+                    : "Taken at the Buy Now price before any bids were placed.",
+                rows,
+                saved: ctx.listPrice > ctx.buyNowPrice ? ctx.listPrice - ctx.buyNowPrice : undefined,
+            };
+        }
+        case "offer-accepted": {
+            const rows = [
+                { label: "Agreed price", value: money(ctx.offeredAmount) },
+                { label: "Asking price when offered", value: money(ctx.listPriceAtOffer) },
+            ];
+            if (ctx.counterAmount !== undefined) {
+                rows.push({ label: "Final counter", value: money(ctx.counterAmount) });
+            }
+            rows.push({ label: "Negotiation", value: plural(ctx.counterRounds, "round", "rounds") }, { label: "Accepted", value: dateText(ctx.acceptedAt) });
+            return {
+                title: "Price agreed by offer",
+                tone: "primary",
+                summary: ctx.counterRounds > 1
+                    ? `Agreed after ${plural(ctx.counterRounds, "round", "rounds")} of counter-offers.`
+                    : "Accepted outright, with no counter-offer.",
+                rows,
+                saved: ctx.listPriceAtOffer > ctx.offeredAmount
+                    ? ctx.listPriceAtOffer - ctx.offeredAmount
+                    : undefined,
+            };
+        }
+        case "pre-order":
+            return {
+                title: "Pre-order",
+                tone: "warning",
+                summary: ctx.balanceDue > 0
+                    ? "A deposit was taken at checkout; the balance is due before dispatch."
+                    : "Paid in full at checkout.",
+                rows: [
+                    { label: "Deposit paid", value: money(ctx.depositAmount) },
+                    { label: "Balance due", value: money(ctx.balanceDue) },
+                    { label: "Expected delivery", value: dateText(ctx.expectedDeliveryDate) },
+                ],
+            };
+        case "prize-draw":
+            return {
+                title: "Prize draw entry",
+                tone: "info",
+                summary: ctx.revealMode === "instant"
+                    ? "The result was revealed immediately."
+                    : "The result is revealed at the scheduled draw.",
+                rows: [
+                    { label: "Entries bought", value: plural(ctx.entryCount, "entry", "entries") },
+                    { label: "Price per entry", value: money(ctx.pricePerEntry) },
+                    { label: "Reveal", value: ctx.revealMode === "instant" ? "Instant" : "Scheduled" },
+                ],
+            };
+        default: {
+            /*
+             * Exhaustive. A seventh variant — the shared-purchase path S5a still
+             * needs — will not compile rather than silently rendering nothing, which
+             * is the failure mode of `default: return null` and is precisely how this
+             * union came to have six populated variants and no reader at all.
+             */
+            const unreachable = ctx;
+            return unreachable;
+        }
+    }
+}
+export function OrderProvenanceCard({ sourceContext, currency, className, }) {
+    // Every order written before W2 has no context at all — absence is normal
+    // and is not an error state to announce.
+    if (!sourceContext)
+        return null;
+    const content = contentFor(sourceContext, currency);
+    if (!content)
+        return null;
+    return (_jsx(Card, { variant: "outlined", padding: "md", className: className, children: _jsxs(Stack, { gap: "sm", children: [_jsxs(Row, { align: "center", gap: "sm", wrap: true, children: [_jsx(Heading, { level: 3, size: "sm", children: content.title }), content.saved !== undefined ? (_jsx(Badge, { variant: "success", children: `Saved ${formatCurrency(content.saved, currency)}` })) : null] }), content.summary ? (_jsx(Text, { size: "sm", color: "muted", children: content.summary })) : null, _jsx(Row, { as: "dl", wrap: true, gap: "md", children: content.rows.map((row) => (_jsx(DescriptionField, { label: row.label, value: row.value }, row.label))) })] }) }));
+}

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

@@ -0,0 +1,14 @@
+import { type DisputeGateOrder, type DisputeKind } from "../../../_internal/shared/features/orders/dispute-reasons";
+export interface RaiseDisputeFormProps {
+    /** The gate reads four dates off this; an `OrderDocument` satisfies it. */
+    order: DisputeGateOrder;
+    /** `GET ?kind=` / `POST` — supplied by the consumer so appkit holds no route. */
+    reasonsEndpoint: string;
+    onSubmit: (input: {
+        kind: DisputeKind;
+        reasonId: string;
+        detail?: string;
+    }) => Promise<void>;
+    onDone?: () => void;
+}
+export declare function RaiseDisputeForm({ order, reasonsEndpoint, onSubmit, onDone, }: RaiseDisputeFormProps): import("react").JSX.Element;

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

@@ -0,0 +1,111 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+/**
+ * The buyer's dispute form: pick a kind, pick a reason, say what happened.
+ *
+ * ## Why the kind comes first
+ *
+ * The two kinds have MUTUALLY EXCLUSIVE gates — an item problem needs the
+ * order to have arrived, a non-delivery needs it not to have. So the kind is
+ * the first choice, it scopes the reason list, and it decides which gate the
+ * server will apply. Offering one merged list of reasons would mean a buyer
+ * could pick "it never arrived" on a delivered order and have the server
+ * refuse them, which reads as the form being broken rather than as the wrong
+ * choice.
+ *
+ * ## The gate is checked HERE for the affordance and AGAIN on the server
+ *
+ * 🛑 This copy decides what to OFFER. The server decides what to ACCEPT, and
+ * it is the authority — `raiseOrderDisputeAction` re-runs `checkDisputeGate`
+ * on the real order. Showing a kind the server would refuse is the dead-end
+ * shape (CLAUDE.md's rule for `OrderCompletionPanel`: never offer a button the
+ * server will refuse), and trusting this copy alone would be a client-side
+ * security gate.
+ */
+import { useCallback, useMemo, useState } from "react";
+import { DISPUTE_KIND, DISPUTE_KIND_LABEL, checkDisputeGate, disputeNotReachedFilableFrom, } from "../../../_internal/shared/features/orders/dispute-reasons.js";
+import { Alert, Button, Div, FieldTextarea, Form, Stack, Text, useToast } from "../../../ui/index.js";
+import { PaginatedSelect } from "../../../ui/components/PaginatedSelect.js";
+import { ACTIONS } from "../../../_internal/shared/actions/action-registry.js";
+import { normalizeError } from "../../../errors/normalize.js";
+export function RaiseDisputeForm({ order, reasonsEndpoint, onSubmit, onDone, }) {
+    const { showToast } = useToast();
+    const [kind, setKind] = useState(null);
+    const [reasonId, setReasonId] = useState(null);
+    const [detail, setDetail] = useState("");
+    const [isPending, setIsPending] = useState(false);
+    /*
+     * Which kinds this order can actually support, with the server's own gate.
+     * A kind that would be refused is shown DISABLED with the reason rather than
+     * hidden: "why can't I report this?" is a question the form should answer,
+     * and a silently missing option looks like a bug.
+     */
+    const kindStates = useMemo(() => DISPUTE_KIND.map((k) => ({
+        kind: k,
+        label: DISPUTE_KIND_LABEL[k],
+        gate: checkDisputeGate(k, order),
+    })), [order]);
+    const filableFrom = useMemo(() => disputeNotReachedFilableFrom(order), [order]);
+    /*
+     * 🛑 Keyed on `kind` so switching kind refetches. `PaginatedSelect` caches
+     * per `loadOptions` identity, so a stable callback would keep showing the
+     * previous kind's reasons — which is the one thing that must never happen
+     * here, because a mismatched reason is refused by the server.
+     */
+    const loadReasons = useCallback(async (query, page) => {
+        if (!kind)
+            return { items: [], hasMore: false };
+        const res = await fetch(`${reasonsEndpoint}?kind=${encodeURIComponent(kind)}`);
+        if (!res.ok) {
+            /*
+             * Surfaced, not swallowed into an empty list. An empty picker is
+             * indistinguishable from "there are no reasons", and the buyer would
+             * sit on a required field with nothing in it (Root Cause #59).
+             */
+            throw new Error("Could not load the list of reasons. Please try again.");
+        }
+        const json = (await res.json());
+        const rows = json.data?.items ?? [];
+        const q = query.trim().toLowerCase();
+        const filtered = q ? rows.filter((r) => r.label.toLowerCase().includes(q)) : rows;
+        return {
+            // `items`, not `options` — checked against `AsyncPage` rather than
+            // guessed; the wrong key yields an empty picker with no error.
+            items: filtered.map((r) => ({ value: r.id, label: r.label })),
+            // The route caps at 50 and the list is short by design; there is no
+            // second page to promise. `page` is unused for the same reason.
+            hasMore: false,
+        };
+    }, [kind, reasonsEndpoint]);
+    const chooseKind = (next) => {
+        setKind(next);
+        // Clearing is required: a reason from the previous kind would be refused.
+        setReasonId(null);
+    };
+    const submit = async () => {
+        if (!kind || !reasonId)
+            return;
+        setIsPending(true);
+        try {
+            await onSubmit({ kind, reasonId, detail: detail.trim() || undefined });
+            showToast("Thanks — we've recorded it and will look into it.", "success");
+            onDone?.();
+        }
+        catch (err) {
+            // The server's message names the next action; show it verbatim rather
+            // than replacing it with a generic failure.
+            showToast(normalizeError(err).message, "error");
+        }
+        finally {
+            setIsPending(false);
+        }
+    };
+    return (_jsx(Form, { onSubmit: (e) => e.preventDefault(), children: _jsxs(Stack, { gap: "md", children: [_jsxs(Stack, { gap: "xs", children: [_jsx(Text, { size: "sm", weight: "semibold", children: "What's the problem?" }), kindStates.map((k) => (_jsxs(Div, { children: [_jsx(Button, { variant: kind === k.kind ? "primary" : "secondary", disabled: !k.gate.allowed, onClick: () => chooseKind(k.kind), children: k.label }), !k.gate.allowed ? (_jsx(Text, { size: "xs", color: "muted", children: k.gate.message })) : null] }, k.kind)))] }), kind ? (_jsxs(_Fragment, { children: [_jsx(Text, { size: "sm", weight: "semibold", children: "Reason" }), _jsx(PaginatedSelect, { ariaLabel: "Reason for the dispute", 
+                            /*
+                             * 🛑 `?? null`, not `?? ""`. PaginatedSelect renders its
+                             * placeholder only on `value == null`; an empty string paints a
+                             * BLANK trigger with no prompt, which reads as a broken control
+                             * rather than an unmade choice.
+                             */
+                            value: reasonId ?? null, onChange: (v) => setReasonId(v), loadOptions: loadReasons, placeholder: "Pick the closest match\u2026" }), _jsx(FieldTextarea, { name: "detail", label: "What happened? (optional)", value: detail, onChange: setDetail, maxLength: 2000 }), kind === "not_reached" && filableFrom ? (_jsx(Alert, { variant: "info", children: `We'll chase the courier. If it turns up before we finish, let us know.` })) : null, _jsx(Button, { type: "submit", action: ACTIONS.SUPPORT["raise-dispute"], isLoading: isPending, disabled: !reasonId, onClick: submit, children: "Report this" })] })) : null] }) }));
+}

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

@@ -28,11 +28,19 @@ import { FormShellContext, useFormShellState, FormErrorSummary, FieldTextarea, }
 import { SectionForm, useSectionFormNav } from "../../shell/index.js";
 import { z } from "zod";
 import { REFUND_COPY } from "../../../_internal/shared/features/orders/refund-copy.js";
+import { resolvePublishedCopy, resolvePublishedValues, } from "../../../_internal/shared/content/published-values.js";
 import { RETURN_REASON_LABEL, selectableReturnReasons, } from "../../../_internal/shared/features/orders/return-reasons.js";
 import { formatCurrency } from "../../../utils/number.formatter.js";
 import { normalizeError } from "../../../errors/normalize.js";
 import { toUserMessage } from "../../../errors/error-display-map.js";
 const ACK_COUNT = REFUND_COPY.request.acknowledgments.length;
+/*
+ * Phase 9 — code-derived values, resolved once. No settings argument: the only
+ * token in this copy is the refund timeline, which has no setting (see the 🛑
+ * on `refundBusinessDaysMin` in the registry), so passing settings would imply
+ * an editable number that does not exist.
+ */
+const PUBLISHED_VALUES = resolvePublishedValues();
 export function RefundRequestView({ order, onSubmitRequest, isLoading = false, className = "", }) {
     /*
      * Does anything in this order carry the final-sale term? Read from the
@@ -83,7 +91,17 @@ export function RefundRequestView({ order, onSubmitRequest, isLoading = false, c
             fields: ["acknowledged"],
             render: ({ values, onChange, errors }) => (_jsxs(Stack, { gap: "sm", children: [REFUND_COPY.request.acknowledgments.map((text, i) => (_jsx(Checkbox, { checked: values.acknowledged[i] ?? false, onChange: () => onChange({
                             acknowledged: values.acknowledged.map((v, idx) => idx === i ? !v : v),
-                        }), label: _jsx(Text, { size: "sm", className: "leading-snug", children: text }), "aria-label": `Acknowledgment ${i + 1}`, "aria-invalid": errors.acknowledged ? "true" : undefined }, i))), errors.acknowledged && (_jsx(Text, { size: "sm", variant: "error", role: "alert", children: errors.acknowledged }))] })),
+                        }), 
+                        /*
+                         * 🛑 Phase 9 — resolved, because this is an ACKNOWLEDGEMENT
+                         * the buyer ticks. `REFUND_COPY`'s refund-timeline line now
+                         * carries `{{refundBusinessDaysMin}}`/`Max` so it has one
+                         * owner instead of being the third of three contradicting
+                         * statements — and an unresolved token inside something a
+                         * buyer is agreeing to is the strongest reason the unknown-key
+                         * rule leaves `{{…}}` VISIBLE rather than blanking it.
+                         */
+                        label: _jsx(Text, { size: "sm", className: "leading-snug", children: resolvePublishedCopy(text, PUBLISHED_VALUES) }), "aria-label": `Acknowledgment ${i + 1}`, "aria-invalid": errors.acknowledged ? "true" : undefined }, i))), errors.acknowledged && (_jsx(Text, { size: "sm", variant: "error", role: "alert", children: errors.acknowledged }))] })),
         },
     ], [order.total, order.currency, hasFinalSaleLine, allowedReasons]);
     const nav = useSectionFormNav(sections, draft);

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

@@ -6,6 +6,10 @@ export { OrderSiblingPayments } from "./OrderSiblingPayments";
 export type { OrderSiblingPaymentsProps } from "./OrderSiblingPayments";
 export { OrderPaymentSummary } from "./OrderPaymentSummary";
 export type { OrderPaymentSummaryProps } from "./OrderPaymentSummary";
+export { OrderProvenanceCard } from "./OrderProvenanceCard";
+export type { OrderProvenanceCardProps } from "./OrderProvenanceCard";
+export { RaiseDisputeForm } from "./RaiseDisputeForm";
+export type { RaiseDisputeFormProps } from "./RaiseDisputeForm";
 export { OrderStatusTimeline } from "./OrderStatusTimeline";
 export type { OrderStatusTimelineProps } from "./OrderStatusTimeline";
 export { RefundHistoryTable } from "./RefundHistoryTable";

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

@@ -3,6 +3,8 @@ export { OrderAddonBadges, } from "./OrderAddonBadges.js";
 export { OrderFilters, ORDER_FILTER_KEYS, ORDER_ADMIN_SORT_OPTIONS, ORDER_SELLER_SORT_OPTIONS, ORDER_USER_SORT_OPTIONS, getOrderFilterKeys, getOrderSortOptions, } from "./OrderFilters.js";
 export { OrderSiblingPayments } from "./OrderSiblingPayments.js";
 export { OrderPaymentSummary } from "./OrderPaymentSummary.js";
+export { OrderProvenanceCard } from "./OrderProvenanceCard.js";
+export { RaiseDisputeForm } from "./RaiseDisputeForm.js";
 export { OrderStatusTimeline } from "./OrderStatusTimeline.js";
 export { RefundHistoryTable } from "./RefundHistoryTable.js";
 export { RefundRequestView } from "./RefundRequestView.js";

package/dist/features/orders/constants/order-lane-tabs.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Order PROVENANCE tabs — the one definition, shared by the buyer's and the
+ * seller's order lists.
+ *
+ * ## Why this file exists
+ *
+ * The buyer's list had these tabs and the seller's did not. A seller could see
+ * every order and could not ask "show me the ones I accepted an offer on" or
+ * "show me the auction wins", which is exactly the split that changes how they
+ * are handled: an auction win has a forfeit deadline, an accepted offer has an
+ * agreed price that is not the listing price.
+ *
+ * Copying the array into the second view would have been the ninth
+ * hand-written enumeration of one union in this codebase (Root Cause #61), so
+ * the labels are a `Record<OrderType, string>` instead: a sixth lane is a
+ * COMPILE error here rather than a tab that silently never appears.
+ *
+ * 🛑 Three things about these ids, each of which has already cost a bug:
+ *
+ * 1. **Every id is EXACTLY a stored `OrderDocument.orderType` value.** Firestore
+ *    `==` is byte-exact, so a tab id that is merely plausible returns zero rows
+ *    forever with no error anywhere (Root Cause #33).
+ *
+ * 2. **`preorder` has NO HYPHEN and that is not a typo to tidy up.** `OrderType`
+ *    spells it `preorder`; `ListingType` spells the same concept `pre-order`.
+ *    Two unions, two spellings, and the tab must match the one actually stored.
+ *
+ * 3. **`standard` must be filtered IN MEMORY, never as a Firestore `==`.**
+ *    Orders written before `orderType` existed carry no such field, and an
+ *    equality excludes every document that lacks it — so the "Normal" tab would
+ *    hide every legacy order while looking like it worked. `mergeOrderScopeFilter`
+ *    and the server-side list both already honour this; see `ORDER_LANE_ALL` for
+ *    the "no filter" sentinel.
+ */
+import type { OrderType } from "../utils/order-splitter";
+/**
+ * The "All" tab's id. An empty string rather than a word, so it can never
+ * collide with a real `orderType` value and so `state.orderType ? … : null`
+ * reads as "no filter" at every call site.
+ */
+export declare const ORDER_LANE_ALL: "";
+/**
+ * 🛑 A `Record<OrderType, string>`, deliberately. Omitting a lane does not
+ * compile, which is the whole point — the buyer's list shipped with four tabs
+ * for five lanes, so pre-order and prize-draw orders were reachable only by
+ * landing on "All" and scrolling.
+ */
+export declare const ORDER_LANE_LABELS: Record<OrderType, string>;
+/**
+ * The stored `orderType` values a lane filter may name, for route-side
+ * validation.
+ *
+ * Derived from `ORDER_LANE_LABELS`, so it cannot drift from the tabs. Both
+ * `/api/user/orders` and `/api/store/orders` had — or would have needed — their
+ * own hand-written copy of these five strings; this is the eleventh
+ * enumeration of one union in this codebase collapsed into the union itself
+ * (Root Cause #61).
+ *
+ * 🛑 Validating against it is load-bearing, not hygiene: an unrecognised value
+ * interpolated into a Sieve filter string is a caller-controlled field name
+ * reaching the query builder.
+ */
+export declare const VALID_ORDER_TYPES: ReadonlySet<string>;
+export interface OrderLaneTab {
+    id: string;
+    label: string;
+}
+/** `All` first, then every lane in `LANE_ORDER`. */
+export declare const ORDER_LANE_TABS: readonly OrderLaneTab[];