@mohasinac/appkit 3.4.8 → 3.5.0

package/dist/_internal/client/features/classified/ClassifiedDetailView.js

@@ -8,7 +8,7 @@ import { MediaImage } from "../../../../features/media/MediaImage";
 import { ROUTES } from "../../../../next/routing/route-map";
 import { formatCurrency } from "../../../../utils/number.formatter";
 const __P = {
-    p4: "p-4",
+    p4: "p-[var(--appkit-space-4)]",
 };
 const __O = {
     hidden: "overflow-hidden",

package/dist/_internal/client/features/digital-code/CodeRevealPanel.js

@@ -4,7 +4,7 @@ import { normalizeError } from "../../../../errors/normalize";
 import { useState } from "react";
 import { Button, Div, Row, Span, Stack, Text } from "../../../../ui";
 const __P = {
-    p4: "p-4",
+    p4: "p-[var(--appkit-space-4)]",
 };
 export function CodeRevealPanel({ orderId, redemptionInstructions, fetchCode, }) {
     const [pending, setPending] = useState(false);

package/dist/_internal/client/features/digital-code/DigitalCodeDetailView.js

@@ -5,7 +5,7 @@ import { MediaImage } from "../../../../features/media/MediaImage";
 import { formatCurrency } from "../../../../utils/number.formatter";
 import { CodeRevealPanel } from "./CodeRevealPanel";
 const __P = {
-    p4: "p-4",
+    p4: "p-[var(--appkit-space-4)]",
 };
 const __O = {
     hidden: "overflow-hidden",

package/dist/_internal/client/features/filters/filter-load-options.js

@@ -11,6 +11,7 @@
  */
 import { apiClient } from "../../../../http/ApiClient";
 import { normalizeError } from "../../../../errors/normalize";
+import { ADMIN_ENDPOINTS, CATEGORY_ENDPOINTS, BRAND_ENDPOINTS } from "../../../../constants/api-endpoints";
 const PAGE_SIZE = 25;
 function buildUrl(base, q, page, extra) {
     const params = new URLSearchParams({
@@ -41,7 +42,7 @@ async function fetchPage(url, mapItem) {
  * @param categoryType Optional filter to narrow to a specific category type (e.g. "brand").
  */
 export function makeCategoryLoadOptions(variant = "admin", categoryType) {
-    const base = variant === "admin" ? "/api/admin/categories" : "/api/categories";
+    const base = variant === "admin" ? ADMIN_ENDPOINTS.CATEGORIES : CATEGORY_ENDPOINTS.LIST;
     return async (q, page) => fetchPage(buildUrl(base, q, page, categoryType ? { categoryType } : undefined), (item) => ({
         value: String(item.id ?? item.slug ?? ""),
         label: String(item.name ?? item.id ?? ""),
@@ -49,7 +50,7 @@ export function makeCategoryLoadOptions(variant = "admin", categoryType) {
     }));
 }
 export function makeCategoryFacetLoadOptions(variant = "public", categoryType) {
-    const base = variant === "admin" ? "/api/admin/categories" : "/api/categories";
+    const base = variant === "admin" ? ADMIN_ENDPOINTS.CATEGORIES : CATEGORY_ENDPOINTS.LIST;
     return async (q, page) => fetchPage(buildUrl(base, q, page, categoryType ? { categoryType } : undefined), (item) => ({
         value: String(item.id ?? item.slug ?? ""),
         label: String(item.name ?? item.id ?? ""),
@@ -57,7 +58,7 @@ export function makeCategoryFacetLoadOptions(variant = "public", categoryType) {
 }
 // ── Brands ────────────────────────────────────────────────────────────────────
 export function makeBrandLoadOptions(variant = "admin") {
-    const base = variant === "admin" ? "/api/admin/brands" : "/api/brands";
+    const base = variant === "admin" ? ADMIN_ENDPOINTS.BRANDS : BRAND_ENDPOINTS.LIST;
     return async (q, page) => fetchPage(buildUrl(base, q, page), (item) => ({
         value: String(item.id ?? item.slug ?? ""),
         label: String(item.name ?? item.id ?? ""),
@@ -65,7 +66,7 @@ export function makeBrandLoadOptions(variant = "admin") {
     }));
 }
 export function makeBrandFacetLoadOptions(variant = "public") {
-    const base = variant === "admin" ? "/api/admin/brands" : "/api/brands";
+    const base = variant === "admin" ? ADMIN_ENDPOINTS.BRANDS : BRAND_ENDPOINTS.LIST;
     return async (q, page) => fetchPage(buildUrl(base, q, page), (item) => ({
         value: String(item.id ?? item.slug ?? ""),
         label: String(item.name ?? item.id ?? ""),
@@ -73,21 +74,21 @@ export function makeBrandFacetLoadOptions(variant = "public") {
 }
 // ── Stores ────────────────────────────────────────────────────────────────────
 export function makeStoreLoadOptions() {
-    return async (q, page) => fetchPage(buildUrl("/api/admin/stores", q, page), (item) => ({
+    return async (q, page) => fetchPage(buildUrl(ADMIN_ENDPOINTS.STORES, q, page), (item) => ({
         value: String(item.id ?? item.slug ?? ""),
         label: String(item.storeName ?? item.name ?? item.id ?? ""),
         meta: item,
     }));
 }
 export function makeStoreFacetLoadOptions() {
-    return async (q, page) => fetchPage(buildUrl("/api/admin/stores", q, page), (item) => ({
+    return async (q, page) => fetchPage(buildUrl(ADMIN_ENDPOINTS.STORES, q, page), (item) => ({
         value: String(item.id ?? item.slug ?? ""),
         label: String(item.storeName ?? item.name ?? item.id ?? ""),
     }));
 }
 // ── Products ──────────────────────────────────────────────────────────────────
 export function makeProductLoadOptions(storeId) {
-    return async (q, page) => fetchPage(buildUrl("/api/admin/products", q, page, storeId ? { storeId } : undefined), (item) => ({
+    return async (q, page) => fetchPage(buildUrl(ADMIN_ENDPOINTS.PRODUCTS, q, page, storeId ? { storeId } : undefined), (item) => ({
         value: String(item.id ?? item.slug ?? ""),
         label: String(item.title ?? item.name ?? item.id ?? ""),
         meta: item,
@@ -95,7 +96,7 @@ export function makeProductLoadOptions(storeId) {
 }
 // ── Users ─────────────────────────────────────────────────────────────────────
 export function makeUserLoadOptions(role) {
-    return async (q, page) => fetchPage(buildUrl("/api/admin/users", q, page, role ? { role } : undefined), (item) => ({
+    return async (q, page) => fetchPage(buildUrl(ADMIN_ENDPOINTS.USERS, q, page, role ? { role } : undefined), (item) => ({
         value: String(item.id ?? item.uid ?? ""),
         label: String(item.displayName ?? item.email ?? item.id ?? ""),
         meta: item,
@@ -103,7 +104,7 @@ export function makeUserLoadOptions(role) {
 }
 // ── Addresses ─────────────────────────────────────────────────────────────────
 export function makeAddressLoadOptions(ownerType) {
-    return async (q, page) => fetchPage(buildUrl("/api/admin/addresses", q, page, ownerType ? { ownerType } : undefined), (item) => ({
+    return async (q, page) => fetchPage(buildUrl(ADMIN_ENDPOINTS.ADDRESSES, q, page, ownerType ? { ownerType } : undefined), (item) => ({
         value: String(item.id ?? ""),
         label: [item.label, item.city, item.state].filter(Boolean).join(", "),
         meta: item,

package/dist/_internal/client/features/layout/DashboardLayoutClient.d.ts

@@ -20,6 +20,7 @@
  */
 import { type ReactNode } from "react";
 import type { DashboardVariant, SidebarNavGroup, SectionResponsive } from "../../../shared/features/layout/types";
+import { type BackgroundConfig } from "../../../../ui";
 export interface DashboardLayoutClientProps {
     /** Drives sidebar component selection + accent colour. */
     variant: DashboardVariant;
@@ -46,6 +47,10 @@ export interface DashboardLayoutClientProps {
     contentSurface?: string;
     /** Override the max-width class on the inner content wrapper. */
     contentMaxWidth?: string;
+    /** Background rendered behind the sidebar + content when the light theme is active. Mirrors `AppLayoutShell`'s prop of the same shape. */
+    lightBackground?: BackgroundConfig;
+    /** Background rendered behind the sidebar + content when the dark theme is active. */
+    darkBackground?: BackgroundConfig;
     children: ReactNode;
 }
-export declare function DashboardLayoutClient({ variant, groups, permissions, activeHref: explicitActiveHref, responsive: _responsive, className, contentPadding, contentSurface, contentMaxWidth, children, }: DashboardLayoutClientProps): import("react").JSX.Element;
+export declare function DashboardLayoutClient({ variant, groups, permissions, activeHref: explicitActiveHref, responsive: _responsive, className, contentPadding, contentSurface, contentMaxWidth, lightBackground, darkBackground, children, }: DashboardLayoutClientProps): import("react").JSX.Element;

package/dist/_internal/client/features/layout/DashboardLayoutClient.js

@@ -30,7 +30,8 @@ import { UserSidebar } from "../../../../features/account/components/UserSidebar
 import { DASHBOARD_DESKTOP_MEDIA_QUERY } from "../../../shared/features/layout/config";
 import { filterNavItems } from "./filterNavItems";
 import { useSiteSettings } from "../../../../core/hooks/useSiteSettings";
-import { Div } from "../../../../ui";
+import { useTheme } from "../../theme";
+import { BackgroundRenderer, Div } from "../../../../ui";
 /**
  * Hoisted drawer-state hook — the matchMedia-aware open/close logic that was
  * triplicated across admin/store/user layouts. Used internally by
@@ -124,9 +125,9 @@ function filterGroups(groups, navConfig, permissions) {
     }))
         .filter((group) => group.items.length > 0);
 }
-const DEFAULT_CONTENT_PADDING = "px-5 py-8 lg:pl-14 lg:pr-6 xl:pl-16 xl:pr-10";
+const DEFAULT_CONTENT_PADDING = "px-[var(--appkit-space-5)] py-[var(--appkit-space-8)] lg:pl-14 lg:pr-6 xl:pl-16 xl:pr-10";
 const DEFAULT_CONTENT_MAX_WIDTH = "max-w-screen-2xl";
-export function DashboardLayoutClient({ variant, groups, permissions, activeHref: explicitActiveHref, responsive: _responsive, className, contentPadding, contentSurface, contentMaxWidth, children, }) {
+export function DashboardLayoutClient({ variant, groups, permissions, activeHref: explicitActiveHref, responsive: _responsive, className, contentPadding, contentSurface, contentMaxWidth, lightBackground, darkBackground, children, }) {
     const pathname = usePathname();
     const activeHref = explicitActiveHref ?? pathname ?? "";
     const storageKey = `appkit:sidebar-open:${variant}`;
@@ -134,11 +135,17 @@ export function DashboardLayoutClient({ variant, groups, permissions, activeHref
     useEffect(() => { closeMobile(); }, [pathname, closeMobile]);
     const { data: settings } = useSiteSettings();
     const navConfig = settings?.navConfig;
+    const { theme } = useTheme();
+    // Explicit props win; otherwise fall back to the same siteSettings.background
+    // the public shell reads, so admin/store/user dashboards match it by default.
+    const resolvedLightBackground = lightBackground ?? settings?.background?.light;
+    const resolvedDarkBackground = darkBackground ?? settings?.background?.dark;
+    const hasBackground = Boolean(resolvedLightBackground?.value || resolvedDarkBackground?.value);
     const filteredGroups = filterGroups(groups, navConfig, permissions);
     const adminGroups = variant === "admin"
         ? filteredGroups
         : groups;
-    return (_jsxs(_Fragment, { children: [variant === "admin" && (_jsx(AdminSidebar, { variant: "sidebar", desktopOpen: desktopOpen, mobileOpen: mobileOpen, activePath: activeHref, groups: adminGroups, onCloseMobile: close, onToggle: toggle, className: className })), variant === "store" && (_jsx(StoreSidebar, { variant: "sidebar", desktopOpen: desktopOpen, mobileOpen: mobileOpen, activeHref: activeHref, items: [], groups: filteredGroups, onCloseMobile: close, onToggle: toggle, className: className })), variant === "user" && (_jsx(UserSidebar, { variant: "sidebar", desktopOpen: desktopOpen, mobileOpen: mobileOpen, items: filteredGroups.flatMap((g) => g.items), groups: filteredGroups, onCloseMobile: close, onToggle: toggle, className: className })), _jsx(Div, { className: [
+    return (_jsxs(_Fragment, { children: [hasBackground && (_jsx(BackgroundRenderer, { mode: theme === "dark" ? "dark" : "light", lightMode: resolvedLightBackground ?? { type: "color", value: "" }, darkMode: resolvedDarkBackground ?? { type: "color", value: "" } })), variant === "admin" && (_jsx(AdminSidebar, { variant: "sidebar", desktopOpen: desktopOpen, mobileOpen: mobileOpen, activePath: activeHref, groups: adminGroups, onCloseMobile: close, onToggle: toggle, className: className })), variant === "store" && (_jsx(StoreSidebar, { variant: "sidebar", desktopOpen: desktopOpen, mobileOpen: mobileOpen, activeHref: activeHref, items: [], groups: filteredGroups, onCloseMobile: close, onToggle: toggle, className: className })), variant === "user" && (_jsx(UserSidebar, { variant: "sidebar", desktopOpen: desktopOpen, mobileOpen: mobileOpen, items: filteredGroups.flatMap((g) => g.items), groups: filteredGroups, onCloseMobile: close, onToggle: toggle, className: className })), _jsx(Div, { className: [
                     "w-full flex-1 flex flex-col min-h-[calc(100dvh-var(--header-height,3.5rem))]",
                     contentPadding ?? DEFAULT_CONTENT_PADDING,
                     contentSurface,

package/dist/_internal/client/features/live/LiveItemDetailView.js

@@ -4,12 +4,12 @@ import { Badge, Container, Div, Heading, Row, Section, Stack, Text, } from "../.
 import { MediaImage } from "../../../../features/media/MediaImage";
 import { formatCurrency } from "../../../../utils/number.formatter";
 const __P = {
-    p4: "p-4",
+    p4: "p-[var(--appkit-space-4)]",
 };
 const __O = {
     hidden: "overflow-hidden",
 };
-const CLS_WARN_BOX = "rounded-lg border border-warning bg-warning-surface p-4 text-sm";
+const CLS_WARN_BOX = "rounded-lg border border-warning bg-warning-surface p-[var(--appkit-space-4)] text-[length:var(--appkit-text-sm)]";
 const CLS_WARN_TITLE = "font-medium text-warning";
 const CLS_WARN_BODY = "mt-1 text-warning";
 export function LiveItemDetailView({ product, isLoading = false, renderActions, }) {

package/dist/_internal/client/features/maintenance/views/AnalysisRunnerView.js

@@ -2,7 +2,9 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { normalizeError } from "../../../../../errors/normalize";
 import * as React from "react";
-import { Button, Div, Heading, Li, Section, Span, Table, Tbody, Td, Text, Th, Thead, Tr, Ul } from "@mohasinac/appkit";
+import { Button, Div, Heading, Input, Li, Section, Span, Table, Tbody, Td, Text, Th, Thead, Tr, Ul } from "@mohasinac/appkit";
+import { Select } from "@mohasinac/appkit/ui";
+import { ADMIN_ENDPOINTS } from "../../../../../constants/api-endpoints";
 export function AnalysisRunnerView() {
     const [days, setDays] = React.useState(7);
     const [source, setSource] = React.useState("all");
@@ -13,7 +15,7 @@ export function AnalysisRunnerView() {
         setRunning(true);
         setError(null);
         try {
-            const res = await fetch("/api/admin/maintenance/analysis", {
+            const res = await fetch(ADMIN_ENDPOINTS.MAINTENANCE_ANALYSIS, {
                 method: "POST",
                 headers: { "Content-Type": "application/json" },
                 body: JSON.stringify({ days, source }),
@@ -34,7 +36,12 @@ export function AnalysisRunnerView() {
             setRunning(false);
         }
     }
-    return (_jsxs(Div, { style: { padding: "1.5rem", maxWidth: "1200px", margin: "0 auto" }, children: [_jsx(Heading, { level: 1, style: { fontSize: "1.5rem", fontWeight: 600 }, children: "Maintenance analysis" }), _jsxs(Div, { style: { display: "flex", gap: "1rem", alignItems: "center", margin: "1rem 0" }, children: [_jsxs("label", { children: ["Days back:\u00A0", _jsx("input", { type: "number", min: 1, max: 30, value: days, onChange: (e) => setDays(Math.max(1, Math.min(30, Number(e.target.value) || 7))), style: { width: 80, padding: "0.35rem 0.5rem", border: "1px solid var(--appkit-color-border)", borderRadius: 4 } })] }), _jsxs("label", { children: ["Source:\u00A0", _jsxs("select", { value: source, onChange: (e) => setSource(e.target.value), style: { padding: "0.35rem 0.5rem", border: "1px solid var(--appkit-color-border)", borderRadius: 4 }, children: [_jsx("option", { value: "all", children: "all" }), _jsx("option", { value: "vercel", children: "server (vercel)" }), _jsx("option", { value: "client", children: "client" }), _jsx("option", { value: "function", children: "function" })] })] }), _jsx(Button, { type: "button", onClick: run, isLoading: running, children: "Run analysis" })] }), error ? _jsx(Text, { as: "p", style: { color: "var(--appkit-color-error)" }, children: error }) : null, report ? _jsx(ReportView, { report: report }) : null] }));
+    return (_jsxs(Div, { style: { padding: "1.5rem", maxWidth: "1200px", margin: "0 auto" }, children: [_jsx(Heading, { level: 1, style: { fontSize: "1.5rem", fontWeight: 600 }, children: "Maintenance analysis" }), _jsxs(Div, { style: { display: "flex", gap: "1rem", alignItems: "center", margin: "1rem 0" }, children: [_jsxs("label", { children: ["Days back:\u00A0", _jsx(Input, { bare: true, type: "number", min: 1, max: 30, value: days, onChange: (e) => setDays(Math.max(1, Math.min(30, Number(e.target.value) || 7))), style: { width: 80, padding: "0.35rem 0.5rem", border: "1px solid var(--appkit-color-border)", borderRadius: 4 } })] }), _jsxs("label", { children: ["Source:\u00A0", _jsx(Select, { options: [
+                                    { value: "all", label: "all" },
+                                    { value: "vercel", label: "server (vercel)" },
+                                    { value: "client", label: "client" },
+                                    { value: "function", label: "function" },
+                                ], value: source, onValueChange: (v) => setSource(v), style: { padding: "0.35rem 0.5rem", border: "1px solid var(--appkit-color-border)", borderRadius: 4 } })] }), _jsx(Button, { type: "button", onClick: run, isLoading: running, children: "Run analysis" })] }), error ? _jsx(Text, { as: "p", style: { color: "var(--appkit-color-error)" }, children: error }) : null, report ? _jsx(ReportView, { report: report }) : null] }));
 }
 function ReportView({ report }) {
     return (_jsxs(Div, { children: [_jsxs(Text, { as: "p", style: { color: "var(--appkit-color-text-muted)" }, children: ["Generated ", report.generatedAt, ". Window: ", report.window.days, "d. Total: ", report.totalErrors, ". Unique users: ", report.uniqueUsers, "."] }), _jsx(ReportSection, { title: "Top codes", children: _jsxs(Table, { style: { width: "100%", fontSize: "0.85rem" }, children: [_jsx(Thead, { children: _jsxs(Tr, { children: [_jsx(Th, { align: "left", children: "Code" }), _jsx(Th, { align: "right", children: "Count" }), _jsx(Th, { align: "right", children: "User impact" })] }) }), _jsx(Tbody, { children: report.topCodes.map((c) => (_jsxs(Tr, { children: [_jsx(Td, { style: { fontFamily: "monospace" }, children: c.code }), _jsx(Td, { align: "right", children: c.count }), _jsx(Td, { align: "right", children: c.userImpact })] }, c.code))) })] }) }), _jsx(ReportSection, { title: "Top routes", children: _jsxs(Table, { style: { width: "100%", fontSize: "0.85rem" }, children: [_jsx(Thead, { children: _jsxs(Tr, { children: [_jsx(Th, { align: "left", children: "Route" }), _jsx(Th, { align: "left", children: "Source" }), _jsx(Th, { align: "right", children: "Count" })] }) }), _jsx(Tbody, { children: report.topRoutes.map((r) => (_jsxs(Tr, { children: [_jsx(Td, { style: { fontFamily: "monospace" }, children: r.route }), _jsx(Td, { children: r.source }), _jsx(Td, { align: "right", children: r.count })] }, `${r.source}:${r.route}`))) })] }) }), report.stackClusters.length > 0 ? (_jsx(ReportSection, { title: `Stack clusters (≥5)`, children: _jsx(Ul, { children: report.stackClusters.map((c) => (_jsxs(Li, { style: { marginBottom: "0.5rem", fontSize: "0.82rem" }, children: [_jsxs(Span, { weight: "bold", children: [c.count, "\u00D7"] }), " ", _jsx(Span, { style: { fontFamily: "monospace" }, children: c.signature }), _jsxs(Div, { style: { color: "var(--appkit-color-text-muted)" }, children: ["sample: ", c.sampleMessage] })] }, c.signature))) }) })) : null, report.burstWindows.length > 0 ? (_jsx(ReportSection, { title: "5xx burst windows", children: _jsx(Ul, { children: report.burstWindows.map((b) => (_jsxs(Li, { children: [b.start, " \u2014 ", b.count, " errors (", b.multiplier, "\u00D7 avg)"] }, b.start))) }) })) : null, _jsx(ReportSection, { title: "Recommendations", children: _jsx(Ul, { children: report.recommendations.map((r, i) => _jsx(Li, { children: r }, i)) }) })] }));

package/dist/_internal/client/features/maintenance/views/ServerErrorsListView.js

@@ -1,7 +1,7 @@
 "use client";
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import * as React from "react";
-import { Anchor, Div, Heading, Label, Span, Table, Tbody, Td, Text, Th, Thead, Tr } from "@mohasinac/appkit";
+import { Anchor, Div, Heading, Input, Label, Span, Table, Tbody, Td, Text, Th, Thead, Tr } from "@mohasinac/appkit";
 const BORDER_STYLE = "1px solid var(--appkit-color-border)";
 const COLUMNS = [
     { key: "occurredAtFmt", label: "When", width: "180px" },
@@ -25,7 +25,7 @@ export function ServerErrorsListView({ title, subtitle, source, rows, detailHref
         return rows.filter((r) => (!codeFilter || r.code.toLowerCase().includes(codeFilter.toLowerCase())) &&
             (!routeFilter || r.route.toLowerCase().includes(routeFilter.toLowerCase())));
     }, [rows, codeFilter, routeFilter]);
-    return (_jsxs(Div, { style: { padding: "1.5rem", maxWidth: "1400px", margin: "0 auto" }, children: [_jsx(Heading, { level: 1, style: { fontSize: "1.5rem", fontWeight: 600 }, children: title }), subtitle ? (_jsx(Text, { as: "p", style: { color: "var(--appkit-color-text-muted)", marginBottom: "1rem" }, children: subtitle })) : null, _jsxs(Div, { style: { display: "flex", gap: "0.75rem", marginBottom: "1rem", alignItems: "center" }, children: [_jsxs(Label, { style: { fontSize: "0.85rem" }, children: ["Code", _jsx("input", { type: "search", value: codeFilter, onChange: (e) => setCodeFilter(e.target.value), placeholder: "e.g. NOT_FOUND", style: { marginLeft: "0.5rem", padding: "0.35rem 0.5rem", border: BORDER_STYLE, borderRadius: 4 } })] }), _jsxs(Label, { style: { fontSize: "0.85rem" }, children: ["Route", _jsx("input", { type: "search", value: routeFilter, onChange: (e) => setRouteFilter(e.target.value), placeholder: "e.g. /api/orders", style: { marginLeft: "0.5rem", padding: "0.35rem 0.5rem", border: BORDER_STYLE, borderRadius: 4 } })] }), _jsxs(Span, { style: { marginLeft: "auto", fontSize: "0.85rem", color: "var(--appkit-color-text-muted)" }, children: [filtered.length, " of ", rows.length, " (source=", source, ")"] })] }), _jsx(Div, { style: { overflowX: "auto", border: BORDER_STYLE, borderRadius: 6 }, children: _jsxs(Table, { style: { width: "100%", borderCollapse: "collapse", fontSize: "0.85rem" }, children: [_jsx(Thead, { style: { background: "var(--appkit-color-bg)" }, children: _jsx(Tr, { children: COLUMNS.map((c) => (_jsx(Th, { style: {
+    return (_jsxs(Div, { style: { padding: "1.5rem", maxWidth: "1400px", margin: "0 auto" }, children: [_jsx(Heading, { level: 1, style: { fontSize: "1.5rem", fontWeight: 600 }, children: title }), subtitle ? (_jsx(Text, { as: "p", style: { color: "var(--appkit-color-text-muted)", marginBottom: "1rem" }, children: subtitle })) : null, _jsxs(Div, { style: { display: "flex", gap: "0.75rem", marginBottom: "1rem", alignItems: "center" }, children: [_jsxs(Label, { style: { fontSize: "0.85rem" }, children: ["Code", _jsx(Input, { bare: true, type: "search", value: codeFilter, onChange: (e) => setCodeFilter(e.target.value), placeholder: "e.g. NOT_FOUND", style: { marginLeft: "0.5rem", padding: "0.35rem 0.5rem", border: BORDER_STYLE, borderRadius: 4 } })] }), _jsxs(Label, { style: { fontSize: "0.85rem" }, children: ["Route", _jsx(Input, { bare: true, type: "search", value: routeFilter, onChange: (e) => setRouteFilter(e.target.value), placeholder: "e.g. /api/orders", style: { marginLeft: "0.5rem", padding: "0.35rem 0.5rem", border: BORDER_STYLE, borderRadius: 4 } })] }), _jsxs(Span, { style: { marginLeft: "auto", fontSize: "0.85rem", color: "var(--appkit-color-text-muted)" }, children: [filtered.length, " of ", rows.length, " (source=", source, ")"] })] }), _jsx(Div, { style: { overflowX: "auto", border: BORDER_STYLE, borderRadius: 6 }, children: _jsxs(Table, { style: { width: "100%", borderCollapse: "collapse", fontSize: "0.85rem" }, children: [_jsx(Thead, { style: { background: "var(--appkit-color-bg)" }, children: _jsx(Tr, { children: COLUMNS.map((c) => (_jsx(Th, { style: {
                                         textAlign: "left",
                                         padding: "0.5rem 0.75rem",
                                         borderBottom: BORDER_STYLE,

package/dist/_internal/client/scaffolds/DashboardScaffold.js

@@ -14,11 +14,13 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
  */
 import * as React from "react";
 import { Div, Main, Nav, Span, Stack } from "../../../ui";
+import { useVisualViewportInset } from "../../../react/hooks/useVisualViewportInset";
 export function DashboardScaffold({ children, slotPageHeader, renderNav, renderBottomNav, slotMenuToggle, initialDrawerOpen = false, className, }) {
     const [drawerOpen, setDrawerOpen] = React.useState(initialDrawerOpen);
     const toggleDrawer = React.useCallback(() => setDrawerOpen((v) => !v), []);
     const ctx = { drawerOpen, toggleDrawer };
+    const isKeyboardOpen = useVisualViewportInset();
     const nav = renderNav ? renderNav(ctx) : null;
     const bottomNav = renderBottomNav ? renderBottomNav(ctx) : nav;
-    return (_jsxs(Div, { layout: "flex", className: `appkit-dashboard-scaffold min-h-screen ${className ?? ""}`, children: [nav ? (_jsx("aside", { className: "sticky top-0 hidden h-screen w-64 shrink-0 overflow-y-auto border-r border-[var(--appkit-color-border)] lg:block", "data-dashboard-slot": "sidebar", children: nav })) : null, nav ? (_jsxs("div", { className: `fixed inset-0 z-40 transition-transform md:block lg:hidden ${drawerOpen ? "translate-x-0" : "-translate-x-full"}`, "data-dashboard-slot": "drawer", "aria-hidden": !drawerOpen, children: [_jsx("div", { className: "absolute inset-0 bg-black/40", onClick: () => setDrawerOpen(false), role: "presentation" }), _jsx(Nav, { "aria-label": "Dashboard sidebar", className: "relative h-full w-64 overflow-y-auto bg-[var(--appkit-color-surface)] shadow-xl", children: nav })] })) : null, _jsxs(Stack, { className: "min-w-0 flex-1", children: [(slotPageHeader || slotMenuToggle) && (_jsxs("div", { className: "sticky top-0 z-20 flex items-center gap-3 border-b border-[var(--appkit-color-border)] bg-[var(--appkit-color-surface)] px-4 py-2", "data-dashboard-slot": "page-header", children: [slotMenuToggle ? (_jsx(Span, { className: "lg:hidden", onClick: toggleDrawer, role: "presentation", children: slotMenuToggle })) : null, _jsx(Div, { className: "min-w-0 flex-1", children: slotPageHeader })] })), _jsx(Main, { className: "min-w-0 flex-1 pb-20 lg:pb-0", "data-dashboard-slot": "main", children: children }), bottomNav ? (_jsx(Nav, { "aria-label": "Bottom navigation", className: "fixed bottom-0 left-0 right-0 z-30 border-t border-[var(--appkit-color-border)] bg-[var(--appkit-color-surface)] lg:hidden", "data-dashboard-slot": "bottom-nav", children: bottomNav })) : null] })] }));
+    return (_jsxs(Div, { layout: "flex", className: `appkit-dashboard-scaffold min-h-screen ${className ?? ""}`, children: [nav ? (_jsx("aside", { className: "sticky top-0 hidden h-screen w-64 shrink-0 overflow-y-auto border-r border-[var(--appkit-color-border)] lg:block", "data-dashboard-slot": "sidebar", children: nav })) : null, nav ? (_jsxs("div", { className: `fixed inset-0 z-40 transition-transform md:block lg:hidden ${drawerOpen ? "translate-x-0" : "-translate-x-full"}`, "data-dashboard-slot": "drawer", "aria-hidden": !drawerOpen, children: [_jsx("div", { className: "absolute inset-0 bg-black/40", onClick: () => setDrawerOpen(false), role: "presentation" }), _jsx(Nav, { "aria-label": "Dashboard sidebar", className: "relative h-full w-64 overflow-y-auto bg-[var(--appkit-color-surface)] shadow-xl", children: nav })] })) : null, _jsxs(Stack, { className: "min-w-0 flex-1", children: [(slotPageHeader || slotMenuToggle) && (_jsxs("div", { className: "sticky top-0 z-20 flex items-center gap-[var(--appkit-space-3)] border-b border-[var(--appkit-color-border)] bg-[var(--appkit-color-surface)] px-[var(--appkit-space-4)] py-[var(--appkit-space-2)]", "data-dashboard-slot": "page-header", children: [slotMenuToggle ? (_jsx(Span, { className: "lg:hidden", onClick: toggleDrawer, role: "presentation", children: slotMenuToggle })) : null, _jsx(Div, { className: "min-w-0 flex-1", children: slotPageHeader })] })), _jsx(Main, { className: "min-w-0 flex-1 pb-[var(--appkit-space-20)] lg:pb-[var(--appkit-space-0)]", "data-dashboard-slot": "main", children: children }), bottomNav ? (_jsx(Nav, { "aria-label": "Bottom navigation", "aria-hidden": isKeyboardOpen, className: `fixed bottom-0 left-0 right-0 z-[var(--appkit-z-bottom-nav)] border-t border-[var(--appkit-color-border)] bg-[var(--appkit-color-surface)] lg:hidden transition-transform duration-200 ease-out ${isKeyboardOpen ? "translate-y-full pointer-events-none" : "translate-y-0"}`, "data-dashboard-slot": "bottom-nav", children: bottomNav })) : null] })] }));
 }

package/dist/_internal/server/features/checkout/actions.d.ts

@@ -1,3 +1,4 @@
+import type { OutOfStockPolicy } from "../../../../features/orders/schemas/index";
 import { type CheckoutPaymentMethod } from "../../../shared/features/checkout/config";
 import { type CheckoutOrderResult } from "./data";
 export interface CreateCheckoutOrderInput {
@@ -15,6 +16,13 @@ export interface CreateCheckoutOrderInput {
     adminBypass?: boolean;
     /** UID of the admin who triggered the bypass. Set when adminBypass is true. */
     adminBypassBy?: string;
+    /**
+     * Buyer's choice for what to do when a cart item is unavailable at
+     * checkout time. Defaults to "skip_items" — preserves this path's
+     * historical behavior (ship the rest of the order) for any caller that
+     * omits the field.
+     */
+    outOfStockPolicy?: OutOfStockPolicy;
 }
 /**
  * Place order(s) from the user's cart in a single Firestore transaction.
@@ -42,6 +50,14 @@ export interface VerifyAndPlaceRazorpayOrderInput {
     /** Required for physical carts; omitted for digital-code-only carts. */
     addressId?: string;
     notes?: string;
+    /**
+     * Buyer's choice for what to do when a cart item is unavailable at
+     * checkout time. Defaults to "cancel_order" — matches this path's
+     * historical (only) behavior for any caller/old-client that omits the
+     * field, since "skip_items" partial fulfillment has no prior precedent
+     * on the Razorpay path.
+     */
+    outOfStockPolicy?: OutOfStockPolicy;
 }
 /**
  * Place order(s) from the user's cart after a Razorpay payment is verified.

package/dist/_internal/server/features/checkout/actions.js

@@ -21,9 +21,9 @@ import { getAdminDb, getAdminRealtimeDb, RTDB_PATHS, } from "../../../../provide
 import { PRODUCT_COLLECTION, PRODUCT_CODES_SUBCOLLECTION } from "../../../../features/products/schemas/firestore";
 import { CART_COLLECTION } from "../../../../features/cart/schemas/index";
 // S-SBUNI-RULES 2026-05-13 — bundle cart-line stock fan-out helpers.
-import { getCartItemMemberIds, getExpandedDecrements, validateCartItemStock, } from "./bundle-expansion";
+import { getCartItemMemberIds, getExpandedDecrements, bucketCartItemsByStock, } from "./bundle-expansion";
 import { consentOtpRef, consentOtpRateLimitRef, CONSENT_OTP_MAX_BYPASS_CREDITS, } from "../../../../features/auth/server";
-import { OrderStatusValues, PaymentStatusValues, PaymentMethodValues, } from "../../../../features/orders/schemas/index";
+import { OrderStatusValues, PaymentStatusValues, PaymentMethodValues, OutOfStockPolicyValues, } from "../../../../features/orders/schemas/index";
 import { getDefaultCurrency } from "../../../../core/index";
 import { verifyPaymentSignatureWithKeys, fetchRazorpayOrder, paiseToRupees, } from "../../../../providers/payment-razorpay/index";
 import { CHECKOUT_DEFAULT_COMMISSIONS, CHECKOUT_DEFAULT_EMI_SETTINGS } from "../../../shared/features/checkout/config";
@@ -32,6 +32,8 @@ import { formatShippingAddress } from "./data";
 import { enforceMaxPerUserForCart, computePrizeRevealDeadline, } from "./prize-bundle-gates";
 import { getListingRule, runSyncPreflight, } from "../../../shared/checkout/rules";
 import { cartIsDigitalOnly } from "../../../shared/listing-types/cart-shipping";
+import { processRefundAction } from "../refunds/actions";
+import { sendNotification } from "../../../../features/admin/actions/notification-actions";
 const AUDIT_LOG_FAIL_MSG = "checkout: audit log failed (non-critical)";
 /**
  * SB-UNI-N — Atomically claim the next available digital code for a confirmed
@@ -236,7 +238,7 @@ function unitPriceFor(item, product) {
  * so the caller can accumulate the checkout-wide `total`.
  */
 async function createOrderForGroup(group, orderType, ctx) {
-    const { paymentMethod, emiTenureMonths, emiSettings, commissions, appliedCoupons, cartSubtotal, couponUsageAccumulator, uid, userName, userEmail, shippingAddress, notes, adminBypass, adminBypassBy, adminBatchId, orderIds, emailsToSend, } = ctx;
+    const { paymentMethod, emiTenureMonths, emiSettings, commissions, appliedCoupons, cartSubtotal, couponUsageAccumulator, uid, userName, userEmail, shippingAddress, notes, adminBypass, adminBypassBy, adminBatchId, orderIds, emailsToSend, outOfStockPolicy, droppedItems, } = ctx;
     const firstItem = group[0].item;
     const firstProduct = group[0].product;
     const groupTotal = group.reduce((sum, { item, product }) => sum + unitPriceFor(item, product) * item.quantity, 0);
@@ -381,6 +383,8 @@ async function createOrderForGroup(group, orderType, ctx) {
         couponDiscount: couponDiscount > 0 ? couponDiscount : undefined,
         appliedDiscounts: appliedDiscounts.length > 0 ? appliedDiscounts : undefined,
         imageUrls: imageUrls.length > 0 ? imageUrls : undefined,
+        outOfStockPolicy,
+        droppedItems: droppedItems.length > 0 ? droppedItems : undefined,
         ...extraOrderFields,
     });
     orderIds.push(order.id);
@@ -429,7 +433,7 @@ async function createOrderForGroup(group, orderType, ctx) {
  * auth + rate-limiting before calling this and supply the resolved user fields.
  */
 export async function createCheckoutOrderAction(input) {
-    const { userId: uid, userName, userEmail, addressId, paymentMethod, emiTenureMonths, notes, excludedProductIds = [], adminBypass = false, adminBypassBy, } = input;
+    const { userId: uid, userName, userEmail, addressId, paymentMethod, emiTenureMonths, notes, excludedProductIds = [], adminBypass = false, adminBypassBy, outOfStockPolicy = OutOfStockPolicyValues.SKIP_ITEMS, } = input;
     const siteSettings = await siteSettingsRepository.getSingleton();
     const commissions = siteSettings?.commissions ?? CHECKOUT_DEFAULT_COMMISSIONS;
     const emiSettings = siteSettings?.emi ?? CHECKOUT_DEFAULT_EMI_SETTINGS;
@@ -555,30 +559,26 @@ export async function createCheckoutOrderAction(input) {
                     productById.set(expansion.productIds[i], doc.data());
                 }
             }
+            // Bundle cart-lines surface the first member as the "product" so
+            // downstream listingType branching (prize-draw) stays sound — bundle
+            // pricing is always "standard" so the prize-draw cap isn't enforced.
+            const bucketed = bucketCartItemsByStock(cartItems, productById, expansion.decrements, (item) => productById.get(getCartItemMemberIds(item)[0]) ?? null);
+            const unavailableItems = bucketed.unavailable;
+            // outOfStockPolicy: "cancel_order" — abort the WHOLE checkout batch if
+            // anything is short. This throw happens before any tx.update/tx.set
+            // below, so Firestore's transaction semantics guarantee zero writes
+            // land — no compensating rollback logic needed.
+            if (outOfStockPolicy === OutOfStockPolicyValues.CANCEL_ORDER && unavailableItems.length > 0) {
+                throw new ValidationError(ERROR_MESSAGES.CHECKOUT.INSUFFICIENT_STOCK);
+            }
             const availableItems = [];
-            const unavailableItems = [];
-            for (const item of cartItems) {
-                const shortfall = validateCartItemStock(item, productById, expansion.decrements);
-                if (shortfall) {
-                    unavailableItems.push({
-                        productId: shortfall.productId,
-                        productTitle: item.productTitle,
-                        requestedQty: item.quantity,
-                        availableQty: shortfall.availableQty,
-                    });
-                    continue;
-                }
-                // Bundle cart-lines surface the first member as the "product" so
-                // downstream listingType branching (prize-draw) stays sound — bundle
-                // pricing is always "standard" so the prize-draw cap isn't enforced.
-                const memberIds = getCartItemMemberIds(item);
-                const representative = productById.get(memberIds[0]);
+            for (const { item, product } of bucketed.available) {
                 // S-SBUNI-RULES 2026-05-13 — sync preflight (prize-pool cap, pre-order
                 // quota) via rule registry. Bundles skip — they bypass the cart path.
                 if (!item.bundleProductIds?.length) {
-                    runSyncPreflight([{ item, product: representative }]);
+                    runSyncPreflight([{ item, product }]);
                 }
-                availableItems.push({ item, product: representative });
+                availableItems.push({ item, product });
             }
             // Apply per-product decrements ONCE per unique product (sums across the
             // cart) so two cart lines sharing a product don't double-decrement.
@@ -664,6 +664,8 @@ export async function createCheckoutOrderAction(input) {
         adminBatchId,
         orderIds,
         emailsToSend,
+        outOfStockPolicy,
+        droppedItems: unavailable,
     };
     for (const { items: group, orderType } of orderGroups) {
         total += await createOrderForGroup(group, orderType, groupCtx);
@@ -708,7 +710,7 @@ export async function attachPaymentAction(input) {
  *   7. Confirmation email + RTDB success signal (both fire-and-forget)
  */
 export async function verifyAndPlaceRazorpayOrderAction(input) {
-    const { userId: uid, userName, userEmail, razorpay_order_id, razorpay_payment_id, razorpay_signature, addressId, notes, } = input;
+    const { userId: uid, userName, userEmail, razorpay_order_id, razorpay_payment_id, razorpay_signature, addressId, notes, outOfStockPolicy = OutOfStockPolicyValues.CANCEL_ORDER, } = input;
     const siteSettings = await siteSettingsRepository.getSingleton();
     const platformFeePercent = siteSettings?.commissions?.platformFeePercent ?? 5;
     const gstPercent = siteSettings?.commissions?.gstPercent ?? 18;
@@ -809,25 +811,39 @@ export async function verifyAndPlaceRazorpayOrderAction(input) {
     // SB-UNI-5 — validate every required member product across the cart with
     // cumulative decrement awareness (two bundles sharing a member must NOT
     // both succeed unless the product has enough stock for the sum).
-    for (const item of cart.items) {
-        const shortfall = validateCartItemStock(item, productByIdPaid, expansionPaid.decrements);
-        if (shortfall) {
-            const exists = productByIdPaid.has(shortfall.productId);
+    //
+    // Out-of-stock policy: unlike the COD/UPI path, Razorpay payment has
+    // ALREADY been captured for the full cart by the time this runs — so
+    // "skip_items" here means placing orders for the available items only and
+    // auto-refunding the dropped items' value (below), not skipping payment.
+    const bucketedPaid = bucketCartItemsByStock(cart.items, productByIdPaid, expansionPaid.decrements, (item) => productByIdPaid.get(getCartItemMemberIds(item)[0]) ?? null);
+    const unavailablePaid = bucketedPaid.unavailable;
+    if (unavailablePaid.length > 0) {
+        for (const u of unavailablePaid) {
+            const exists = productByIdPaid.has(u.productId);
             const reason = exists ? "stock_insufficient" : "product_unavailable";
             failedCheckoutRepository
                 .logPayment(uid, reason, exists
-                ? `Product ${shortfall.productId} has ${shortfall.availableQty} left, requested ${item.quantity}`
-                : `Product ${shortfall.productId} not published`, {
+                ? `Product ${u.productId} has ${u.availableQty} left, requested ${u.requestedQty}`
+                : `Product ${u.productId} not published`, {
                 gatewayOrderId: razorpay_order_id,
                 gatewayPaymentId: razorpay_payment_id,
                 addressId,
             })
                 .catch((err) => { void normalizeError(err); serverLogger.warn(AUDIT_LOG_FAIL_MSG, { error: err instanceof Error ? err.message : String(err) }); });
-            throw new ValidationError(exists
-                ? ERROR_MESSAGES.CHECKOUT.INSUFFICIENT_STOCK
-                : ERROR_MESSAGES.CHECKOUT.PRODUCT_UNAVAILABLE);
         }
     }
+    // outOfStockPolicy: "cancel_order" (also the default for old clients that
+    // omit the field) — reject the whole checkout batch, exactly like every
+    // Razorpay checkout behaved before this policy existed.
+    if (outOfStockPolicy === OutOfStockPolicyValues.CANCEL_ORDER && unavailablePaid.length > 0) {
+        throw new ValidationError(ERROR_MESSAGES.CHECKOUT.INSUFFICIENT_STOCK);
+    }
+    // Mirrors the COD/UPI path's all-unavailable guard — regardless of policy,
+    // there is nothing to place an order for.
+    if (bucketedPaid.available.length === 0) {
+        throw new ValidationError(ERROR_MESSAGES.CHECKOUT.INSUFFICIENT_STOCK);
+    }
     {
         // SB-UNI-5 2026-05-13 — bundle cart-lines use item.price (locked
         // bundlePriceInPaise) instead of the representative member's product.price.
@@ -855,7 +871,11 @@ export async function verifyAndPlaceRazorpayOrderAction(input) {
         }
     }
     const appliedCoupons = cart.appliedCoupons ?? [];
-    const orderGroups = splitCartIntoOrderGroups(productChecks);
+    // "skip_items" (or an all-available cart under any policy) — build order
+    // groups from the available bucket only. Dropped items are never ordered;
+    // their value is refunded below since Razorpay already captured payment
+    // for the full cart before this stock check ran.
+    const orderGroups = splitCartIntoOrderGroups(bucketedPaid.available);
     const orderIds = [];
     let total = 0;
     const emailsToSend = [];
@@ -975,6 +995,19 @@ export async function verifyAndPlaceRazorpayOrderAction(input) {
             paymentStatus: PaymentStatusValues.PAID,
             paymentMethod: PaymentMethodValues.ONLINE,
             paymentId: razorpay_payment_id,
+            paymentRecord: {
+                method: "razorpay",
+                transactionId: razorpay_payment_id,
+                amountPaise: orderTotal,
+                paidAt: new Date(),
+                verifiedBy: "razorpay-webhook",
+                verificationMethod: "webhook",
+                gatewayRef: {
+                    orderId: razorpay_order_id,
+                    paymentId: razorpay_payment_id,
+                    signature: razorpay_signature,
+                },
+            },
             shippingAddress,
             notes,
             platformFee,
@@ -983,6 +1016,8 @@ export async function verifyAndPlaceRazorpayOrderAction(input) {
             couponDiscount: couponDiscount > 0 ? couponDiscount : undefined,
             appliedDiscounts: appliedDiscounts.length > 0 ? appliedDiscounts : undefined,
             imageUrls: imageUrls.length > 0 ? imageUrls : undefined,
+            outOfStockPolicy,
+            droppedItems: unavailablePaid.length > 0 ? unavailablePaid : undefined,
             ...extraOrderFields,
         });
         orderIds.push(order.id);
@@ -1044,6 +1079,80 @@ export async function verifyAndPlaceRazorpayOrderAction(input) {
         const otpRefForDelete = consentOtpRef(db, uid, addressId);
         safeFireAndForget(otpRefForDelete.delete(), "checkout: delete OTP consent ref after Razorpay payment");
     }
+    // outOfStockPolicy: "skip_items" — auto-refund the dropped items' value.
+    // Razorpay already captured payment for the FULL cart before this stock
+    // check ran, so anything not placed as an order must be given back.
+    // AWAITED (not fire-and-forget) — this moves money. On failure the orders
+    // themselves are NOT rolled back (they're already validly created and
+    // paid); instead the failure is surfaced via order.refundPending + an
+    // admin notification, never silently dropped (Rule #8).
+    if (unavailablePaid.length > 0 && orderIds.length > 0) {
+        const droppedValueInPaise = unavailablePaid.reduce((sum, u) => sum + (productByIdPaid.get(u.productId)?.price ?? 0) * u.requestedQty, 0);
+        const primaryOrderId = orderIds[0];
+        if (droppedValueInPaise > 0) {
+            try {
+                const primaryOrder = await unitOfWork.orders.findById(primaryOrderId);
+                // Cap defensively at the primary order's total — processRefundAction
+                // rejects any amount exceeding order.totalPrice, and a multi-order
+                // batch's dropped-items value isn't cleanly attributable to a single
+                // order (Razorpay refunds are keyed by paymentId, not orderId; the
+                // FIRST order created in this batch is used as the refund's book-
+                // keeping anchor).
+                const refundAmount = primaryOrder
+                    ? Math.min(droppedValueInPaise, primaryOrder.totalPrice)
+                    : droppedValueInPaise;
+                const refundResult = await processRefundAction({
+                    orderId: primaryOrderId,
+                    type: "partial",
+                    amountInPaise: refundAmount,
+                    reason: `Automatic refund — ${unavailablePaid.length} item(s) unavailable at checkout: ${unavailablePaid.map((u) => u.productTitle).join(", ")}`,
+                    method: "razorpay",
+                    razorpayPaymentId: razorpay_payment_id,
+                    confirmIrrevocable: true,
+                    refundedBy: "system:checkout-auto-refund",
+                });
+                if (!refundResult.ok) {
+                    throw new Error(refundResult.error ?? "Automatic refund failed");
+                }
+            }
+            catch (refundErr) {
+                void normalizeError(refundErr);
+                serverLogger.warn("verifyAndPlaceRazorpayOrderAction: automatic partial refund for dropped items failed — flagging for manual follow-up", {
+                    orderId: primaryOrderId,
+                    droppedValueInPaise,
+                    err: refundErr instanceof Error ? refundErr.message : String(refundErr),
+                });
+                await unitOfWork.orders
+                    .update(primaryOrderId, { refundPending: true })
+                    .catch((updErr) => {
+                    void normalizeError(updErr);
+                    serverLogger.error("verifyAndPlaceRazorpayOrderAction: failed to flag refundPending after auto-refund failure", { orderId: primaryOrderId, err: updErr instanceof Error ? updErr.message : String(updErr) });
+                });
+                // Best-effort admin fan-out — mirrors onScamReportCreate's employee
+                // notification pattern. Never allowed to throw past this point.
+                try {
+                    const admins = await userRepository.list({ filters: "role==admin", page: 1, pageSize: 100 });
+                    await Promise.all(admins.items
+                        .filter((a) => !!a.id)
+                        .map((admin) => sendNotification({
+                        userId: admin.id,
+                        type: "system",
+                        priority: "high",
+                        title: "Automatic refund failed",
+                        message: `Automatic refund failed for order ${primaryOrderId} (${unavailablePaid.length} unavailable item(s)) — manual refund required.`,
+                        relatedId: primaryOrderId,
+                        relatedType: "order",
+                        userEmail: admin.email ?? undefined,
+                        userPhone: admin.phoneNumber ?? undefined,
+                    }).catch((notifErr) => serverLogger.error("Failed to notify admin of failed auto-refund (non-fatal)", notifErr))));
+                }
+                catch (notifyErr) {
+                    void normalizeError(notifyErr);
+                    serverLogger.error("verifyAndPlaceRazorpayOrderAction: failed to query admins for failed auto-refund notification", { orderId: primaryOrderId });
+                }
+            }
+        }
+    }
     if (emailsToSend.length > 0) {
         Promise.all(emailsToSend.map((e) => sendOrderConfirmationEmail(e))).catch((err) => serverLogger.error("Order confirmation email error:", err));
     }
@@ -1052,5 +1161,10 @@ export async function verifyAndPlaceRazorpayOrderAction(input) {
         .ref(`${RTDB_PATHS.PAYMENT_EVENTS}/${razorpay_order_id}`)
         .update({ status: "success", orderIds, updatedAt: Date.now() })
         .catch((err) => serverLogger.warn("Payment event RTDB signal failed (non-critical)", { err }));
-    return { orderIds, total, itemCount: orderIds.length };
+    return {
+        orderIds,
+        total,
+        itemCount: orderIds.length,
+        ...(unavailablePaid.length > 0 ? { unavailableItems: unavailablePaid } : {}),
+    };
 }