@mohasinac/appkit 4.30.18 → 4.30.19

package/dist/features/about/components/DeveloperView.js

@@ -1,5 +1,6 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { normalizeError } from "../../../errors/normalize";
+import { serverLogger } from "../../../monitoring/server-logger";
 import { Anchor, Avatar, Badge, Div, Heading, Row, Section, Span, Stack, Text, TextLink } from "../../../ui";
 import { ROUTES } from "../../../constants";
 import { PAGE_CONTAINER } from "../../../_internal/shared/styles/page";
@@ -21,8 +22,12 @@ export async function DeveloperView({ labels = {} }) {
         milestones = Array.isArray(aboutContent.milestones) ? aboutContent.milestones : [];
     }
     catch (_err) {
-        void normalizeError(_err);
-        // Firestore unavailable — render the empty state below rather than crash.
+        // Firestore unavailable — render the empty state below rather than crash,
+        // but say so: an empty Developers page is indistinguishable from a settings
+        // document that genuinely has no `isDeveloper` members.
+        serverLogger.warn("about.developerView: siteSettings.aboutContent read failed", {
+            error: normalizeError(_err).message,
+        });
     }
     const developers = teamMembers.filter((m) => m.isDeveloper);
     return (_jsxs(Div, { className: "-mx-4 md:-mx-6 lg:-mx-8 -mt-6 sm:-mt-8 lg:-mt-10", children: [_jsx(Section, { color: "inverse", tone: "accent-banner", padding: "banner", children: _jsxs(Div, { className: `${page.container.sm}`, children: [_jsx(Heading, { color: "inverse", level: 1, variant: "none", className: "mb-3", children: labels.title ?? "Meet the Developer" }), _jsx(Text, { color: "inverse", variant: "none", className: "/80", size: "sm", children: labels.subtitle ?? "The person building LetItRip, one feature at a time." })] }) }), _jsxs(Div, { className: `${page.container.sm}`, padding: "content-banner", children: [developers.length === 0 ? (_jsx(Text, { variant: "secondary", children: labels.empty ?? "Developer profile coming soon." })) : (_jsx(Stack, { gap: "xl", children: developers.map((dev) => (_jsxs(Stack, { gap: "md", surface: "default", padding: "lg", rounded: "xl", border: "default", children: [_jsxs(Row, { gap: "md", align: "center", children: [_jsx(Avatar, { src: dev.photoUrl, name: dev.name, alt: dev.name, size: "lg" }), _jsxs(Stack, { gap: "xs", children: [_jsx(Heading, { level: 2, children: dev.name }), _jsxs(Row, { gap: "xs", wrap: true, children: [_jsx(Span, { size: "xs", weight: "bold", className: "text-primary tracking-wide", transform: "uppercase", children: dev.role }), dev.isFounder && _jsx(Badge, { variant: "primary", size: "xs", children: "Founder" }), _jsx(Badge, { variant: "secondary", size: "xs", children: "Developer" })] })] })] }), _jsx(Text, { variant: "secondary", className: "leading-relaxed", children: dev.bio }), dev.githubUrl && (_jsx(Anchor, { href: dev.githubUrl, tone: "brand", size: "sm", underline: "hover", children: "GitHub \u2197" }))] }, dev.name))) })), milestones.length > 0 && (_jsxs(Div, { className: "mt-14 border-t", border: "default", padding: "t-xl", children: [_jsx(Heading, { level: 3, className: "mb-6", color: "muted", size: "sm", weight: "semibold", transform: "uppercase", children: labels.journeyTitle ?? "The Journey" }), _jsx(Stack, { className: "relative border-l-2 border-primary/30 max-w-2xl pl-[2rem]", gap: "lg", children: milestones.map(({ year, text }) => (_jsxs(Div, { className: "relative", children: [_jsx(Div, { className: "absolute -left-10 top-1 w-4 h-4 bg-primary border-2 border-white", rounded: "full" }), _jsx(Span, { size: "xs", weight: "bold", className: "text-primary tracking-wide", transform: "uppercase", children: year }), _jsx(Text, { className: "mt-1", children: text })] }, year))) })] })), _jsx(Div, { className: "mt-10", children: _jsx(TextLink, { href: String(ROUTES.PUBLIC.ABOUT), variant: "muted", size: "sm", children: labels.backToTeam ?? "← Meet the whole team" }) })] })] }));

package/dist/features/about/components/PolicyPageView.js

@@ -1,5 +1,6 @@
 import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
 import { normalizeError } from "../../../errors/normalize";
+import { serverLogger } from "../../../monitoring/server-logger";
 import { Row } from "@mohasinac/appkit/ui";
 import { ROUTES } from "../../../constants";
 import { PAGE_CONTAINER } from "../../../_internal/shared/styles/page";
@@ -72,7 +73,14 @@ export async function PolicyPageView({ policy, }) {
     }
     catch (_err) {
         void normalizeError(_err);
-        // Firestore unavailable — fall back to i18n
+        // Falls back to the bundled i18n copy below, which is a complete policy in
+        // its own right — but an admin who has overridden this page would silently
+        // see the old text, so the failure has to be visible to an operator.
+        serverLogger.warn("about.policyPageView: siteSettings.legalPages read failed", {
+            policy,
+            field: meta.firestoreField,
+            error: normalizeError(_err).message,
+        });
     }
     // i18n fallback sections
     const rawSections = t.raw("sections");

package/dist/features/about/components/PublicProfileView.js

@@ -2,6 +2,7 @@ import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-run
 import Link from "next/link";
 import { getPublicUserProfile, getProfileStoreProducts, getReviewsAuthoredBy, getReviewsReceivedBy } from "../../auth/actions/profile-actions";
 import { storeRepository } from "../../stores/repository/store.repository";
+import { safeRead } from "../../../errors/safe-read";
 import { ROUTES } from "../../../constants";
 import { PAGE_CONTAINER } from "../../../_internal/shared/styles/page";
 import { FLEX_CENTER } from "../../../_internal/shared/styles/themed";
@@ -64,13 +65,30 @@ export async function PublicProfileView({ userId, tab, }) {
     const flex = { center: FLEX_CENTER };
     const { getTranslations } = await import("next-intl/server");
     const t = await getTranslations("publicProfile");
-    const profile = await getPublicUserProfile(userId).catch(() => null);
+    // The profile IS this page's subject — a read failure must surface, not turn
+    // into the same `null` a genuinely missing user produces. The `null` return
+    // from getPublicUserProfile still means "no such user".
+    const profile = await getPublicUserProfile(userId);
     const storeId = profile?.storeSlug ?? null;
     const [products, store, reviewsAuthored, reviewsReceivedAsBuyer] = await Promise.all([
-        storeId ? getProfileStoreProducts(storeId).catch(() => []) : Promise.resolve([]),
-        storeId ? storeRepository.findById(storeId).catch(() => null) : Promise.resolve(null),
-        getReviewsAuthoredBy(userId).catch(() => []),
-        getReviewsReceivedBy(userId).catch(() => []),
+        storeId
+            ? safeRead(() => getProfileStoreProducts(storeId), {
+                route: "/profile/[userId]",
+                key: "profile.storeProducts",
+                fallback: [],
+            })
+            : Promise.resolve([]),
+        storeId
+            ? safeRead(() => storeRepository.findById(storeId), {
+                route: "/profile/[userId]",
+                key: "profile.store",
+                fallback: null,
+            })
+            : Promise.resolve(null),
+        // Both already degrade internally via safeRead — anything still thrown here
+        // is a mapping bug, which should surface rather than render an empty rail.
+        getReviewsAuthoredBy(userId),
+        getReviewsReceivedBy(userId),
     ]);
     const isSeller = isSellerUser(profile) || isAdminUser(profile);
     // For sellers: lead with store identity (name + logo). For buyers: user identity.

package/dist/features/account/components/AddressForm.js

@@ -102,7 +102,7 @@ export function AddressForm({ initialData, onSubmit, onCancel, isLoading = false
         }
         catch (err) {
             void normalizeError(err);
-            showToast(err instanceof Error ? err.message : "Failed to save address", "error");
+            showToast("Failed to save address", "error");
         }
     }, [formData, onSubmit, showToast, setFieldError, clearErrors, markSubmitAttempted]);
     useEffect(() => {

package/dist/features/account/components/NotificationBell.js

@@ -1,6 +1,7 @@
 "use client";
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { normalizeError } from "../../../errors/normalize";
+import { toUserMessage } from "../../../errors/error-display-map";
 import { useCallback, useRef, useState } from "react";
 import { Button, Div, Heading, Li, Row, Span, Spinner, Stack, Text, TextLink, Ul, useToast } from "../../../ui";
 import { useClickOutside, useMessage } from "../../../react";
@@ -52,7 +53,7 @@ export function NotificationBell({ limit = 10, viewAllHref, labels, icons, rende
         }
         catch (err) {
             void normalizeError(err);
-            showToast(err instanceof Error ? err.message : "Failed to mark notification as read", "error");
+            showToast("Failed to mark notification as read", "error");
         }
     }, [markRead, refetch, showToast]);
     const emitSuccess = onMarkAllReadSuccess ?? showSuccess;
@@ -63,12 +64,12 @@ export function NotificationBell({ limit = 10, viewAllHref, labels, icons, rende
             emitSuccess(labels.markAllRead);
         }
         catch (err) {
-            void normalizeError(err);
+            const e = normalizeError(err);
             if (onMarkAllReadError) {
                 onMarkAllReadError(labels.error);
             }
             else {
-                showToast(err instanceof Error ? err.message : labels.error, "error");
+                showToast(toUserMessage(e.code, undefined, { fallback: labels.error }), "error");
             }
         }
     }, [

package/dist/features/account/components/NotificationPreferencesPanel.js

@@ -79,7 +79,7 @@ export function NotificationPreferencesPanel({ fetchUrl = ACCOUNT_ENDPOINTS.NOTI
         }
         catch (err) {
             void normalizeError(err);
-            showToast(err instanceof Error ? err.message : "Failed to save preferences.", "error");
+            showToast("Failed to save preferences.", "error");
         }
         finally {
             setSaving(false);

package/dist/features/account/components/UserOffersPanel.js

@@ -55,7 +55,7 @@ function BuyerOfferCard({ offer, onAcceptCounter, onWithdraw, onCheckout, onUpda
                     onNeedsLogin();
                 }
                 else {
-                    setError(err instanceof Error ? err.message : "Something went wrong.");
+                    setError("Something went wrong.");
                 }
             }
         });

package/dist/features/admin/components/AdminFulfillmentView.js

@@ -40,12 +40,15 @@ export function AdminFulfillmentView({ initialStoreId, initialStoreName, }) {
             setOrders(res.orders ?? []);
         }
         catch (err) {
-            void normalizeError(err);
+            // An empty fulfilment queue is a normal, expected state, so a swallowed
+            // failure here reads as "nothing to pack" — matching the rest of this
+            // file, surface it instead.
+            showToast(normalizeError(err).message, "error");
         }
         finally {
             setIsLoading(false);
         }
-    }, []);
+    }, [showToast]);
     useEffect(() => {
         if (storeId)
             void fetchOrders(storeId);

package/dist/features/admin/components/AdminMediaView.js

@@ -48,7 +48,7 @@ function MediaBrowser({ onCopy }) {
         }
         catch (err) {
             void normalizeError(err);
-            setError(err instanceof Error ? err.message : "Failed to load");
+            setError("Failed to load");
         }
         finally {
             setIsLoading(false);
@@ -108,7 +108,7 @@ export function AdminMediaView({ labels = {}, children, ...rest }) {
         catch (err) {
             void normalizeError(err);
             setOperationMessage("Failed to discard staged media uploads.");
-            showToast(err instanceof Error ? err.message : "Failed to clear uploads.", "error");
+            showToast("Failed to clear uploads.", "error");
         }
     }, [cleanup, stagedUrls, showToast]);
     const copyToClipboard = React.useCallback(async (url) => {
@@ -121,7 +121,7 @@ export function AdminMediaView({ labels = {}, children, ...rest }) {
         catch (err) {
             void normalizeError(err);
             setOperationMessage("Could not copy URL to clipboard.");
-            showToast(err instanceof Error ? err.message : "Failed to copy.", "error");
+            showToast("Failed to copy.", "error");
         }
     }, [showToast]);
     if (hasChildren) {

package/dist/features/analytics/types.d.ts

@@ -2,5 +2,5 @@
  * page-views.repository.ts (server-only, imports firebase-admin) so the
  * client-side tracker component can import just this without pulling
  * firebase-admin into the client bundle. */
-export declare const PAGE_VIEW_ENTITY_TYPES: readonly ["product", "store", "category", "homepage", "auction", "review", "user-profile", "blog", "event", "pre-order", "prize-draw", "classified", "digital-code", "live", "bundle", "grouped-listing"];
+export declare const PAGE_VIEW_ENTITY_TYPES: readonly ["product", "store", "category", "homepage", "auction", "review", "user-profile", "blog", "event", "pre-order", "prize-draw", "classified", "digital-code", "live", "bundle", "grouped-listing", "listing"];
 export type PageViewEntityType = (typeof PAGE_VIEW_ENTITY_TYPES)[number];

package/dist/features/analytics/types.js

@@ -21,4 +21,17 @@ export const PAGE_VIEW_ENTITY_TYPES = [
     /** A `groupedListings` document's own page. Distinct from "bundle" — a
      *  bundle is a priced, all-or-nothing set; a group is pick-as-you-wish. */
     "grouped-listing",
+    /**
+     * A public BROWSE page — `/products`, `/auctions`, `/stores`, … — as opposed
+     * to one entity's detail page.
+     *
+     * 🛑 `entityId` must be the bare route name ("products"), NEVER the filtered
+     * URL. `pageViews` doc ids are `${date}_${entityType}_${entityId}` with a
+     * `FieldValue.increment`, so a bounded id costs ONE write per day per page,
+     * while keying on a query string would create a new document per filter
+     * combination — unbounded doc creation on the highest-traffic pages, against
+     * the Firestore write budget in Rule #6. The full URL still travels in the
+     * `url` field, which is recorded but not part of the key.
+     */
+    "listing",
 ];

package/dist/features/auctions/components/AuctionDetailPageView.js

@@ -2,6 +2,7 @@ import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-run
 import Link from "next/link";
 import { productRepository } from "../../../repositories";
 import { listBidsByProduct } from "../../auctions/actions/bid-actions";
+import { safeRead } from "../../../errors/safe-read";
 const __P = {
     p3: "p-[var(--appkit-space-3)]",
     p4: "p-[var(--appkit-space-4)]",
@@ -62,11 +63,14 @@ function renderAuctionStoreReviews(storeSlug) {
     return (_jsxs(Section, { className: "mt-10", children: [_jsx(Heading, { level: 2, className: "mb-2", color: "primary", size: "xl", weight: "semibold", children: "Store Reviews" }), _jsx(ReviewsListingPanel, { source: { kind: "store", storeSlug }, stateMode: "local", context: "store", emptyLabel: "This store has no reviews yet." })] }));
 }
 export async function AuctionDetailPageView({ id, initialAuction, onPlaceBid, onBuyNow, productFeatures }) {
+    // The auction IS this page's subject. A read failure must surface rather than
+    // become the same `undefined` a genuinely missing slug produces — the
+    // "Auction Not Found" branch below still handles that real case.
     const product = initialAuction !== undefined
         ? (initialAuction ?? undefined)
-        : await productRepository.findByIdOrSlug(id).catch(() => undefined);
+        : await productRepository.findByIdOrSlug(id);
     const bidsResult = product
-        ? await listBidsByProduct(String(product.id), { pageSize: 5 }).catch(() => null)
+        ? await safeRead(() => listBidsByProduct(String(product.id), { pageSize: 5 }), { route: "/auctions/[slug]", key: "auction.bidHistory", fallback: null })
         : null;
     const storeId = product?.storeId;
     if (!product) {

package/dist/features/auctions/components/MarketplaceAuctionCard.js

@@ -163,8 +163,10 @@ export function MarketplaceAuctionCard({ product, buyoutPrice, className = "", v
             await toggle();
         }
         catch (_err) {
+            // useWishlistToggle rolls back its optimistic state and raises its own
+            // toast on failure, so the heart returns to its true value on screen.
+            // Reporting again here would double-notify for one user action.
             void normalizeError(_err);
-            // The hook rolls back optimistic state when the mutation fails.
         }
     }, [toggle]);
     const countdownClass = isEnded

package/dist/features/auth/actions/profile-actions.js

@@ -5,6 +5,7 @@
  * Auth, rate-limiting, and Next.js specifics are handled by the consumer.
  */
 import { maskPublicReview } from "../../../security";
+import { safeRead } from "../../../errors/safe-read";
 import { finalizeStagedMediaField } from "../../media/finalize";
 import { userRepository } from "../repository/user.repository";
 import { sessionRepository } from "../repository/session.repository";
@@ -65,7 +66,7 @@ export async function getPublicUserProfile(userId) {
 }
 /** Fetch approved reviews for a store. storeId === storeSlug in this project. */
 export async function getSellerReviews(storeId) {
-    const snapshot = await reviewRepository.findApprovedByStore(storeId).catch(() => []);
+    const snapshot = await safeRead(() => reviewRepository.findApprovedByStore(storeId), { route: "/profile/[userId]", key: "reviews.findApprovedByStore", fallback: [] });
     return snapshot.map((r) => ({
         id: r.id,
         productId: r.productId,
@@ -94,7 +95,7 @@ export async function getProfileStoreProducts(storeId) {
 }
 /** Approved product reviews written by this user as a buyer. Excludes seller→buyer ratings. */
 export async function getReviewsAuthoredBy(userId) {
-    const all = await reviewRepository.findApprovedByUser(userId).catch(() => []);
+    const all = await safeRead(() => reviewRepository.findApprovedByUser(userId), { route: "/profile/[userId]", key: "reviews.findApprovedByUser", fallback: [] });
     // reviewerRole:"seller" means this user rated a buyer — not a product review
     const snapshot = all.filter((r) => r.reviewerRole !== "seller");
     return snapshot.map((r) => ({
@@ -121,7 +122,7 @@ export async function getReviewsAuthoredBy(userId) {
 }
 /** Approved seller→buyer reviews received by this buyer. */
 export async function getReviewsReceivedBy(userId) {
-    const snapshot = await reviewRepository.findByReviewee(userId).catch(() => []);
+    const snapshot = await safeRead(() => reviewRepository.findByReviewee(userId), { route: "/profile/[userId]", key: "reviews.findByReviewee", fallback: [] });
     return snapshot.map((r) => ({
         id: r.id,
         productId: r.productId,

package/dist/features/auth/components/ForgotPasswordView.js

@@ -22,7 +22,7 @@ export function ForgotPasswordView({ onSubmit, isLoading = false, error, success
             }
             catch (err) {
                 void normalizeError(err);
-                showToast(err instanceof Error ? err.message : "Failed to send reset link", "error");
+                showToast("Failed to send reset link", "error");
             }
         };
     }

package/dist/features/auth/components/LoginForm.js

@@ -27,7 +27,7 @@ export function LoginForm({ onSubmit, onGoogleLogin, isLoading = false, error, l
                                     }
                                     catch (err) {
                                         void normalizeError(err);
-                                        showToast(err instanceof Error ? err.message : "Sign in failed", "error");
+                                        showToast("Sign in failed", "error");
                                     }
                                 }, children: isLoading
                                     ? (labels.submittingLabel ?? "Signing in…")

package/dist/features/auth/components/RegisterForm.js

@@ -39,7 +39,7 @@ export function RegisterForm({ onSubmit, isLoading = false, error, success, labe
                                     }
                                     catch (err) {
                                         void normalizeError(err);
-                                        showToast(err instanceof Error ? err.message : "Registration failed", "error");
+                                        showToast("Registration failed", "error");
                                     }
                                 }, children: isLoading
                                     ? (labels.submittingLabel ?? "Creating account…")

package/dist/features/auth/components/ResetPasswordView.js

@@ -30,7 +30,7 @@ export function ResetPasswordView({ oobCode, onSubmit, isLoading = false, error,
             }
             catch (err) {
                 void normalizeError(err);
-                showToast(err instanceof Error ? err.message : "Password reset failed", "error");
+                showToast("Password reset failed", "error");
             }
         };
     }

package/dist/features/auth/hooks/useAuth.js

@@ -315,6 +315,9 @@ export function useRegister(options) {
             // fail registration — the user can re-request verification later.
             try {
                 await authProvider.sendEmailVerification();
+                // Non-fatal by design: the account already exists, and the user can
+                // re-request verification from Settings at any time. Firebase surfaces
+                // its own send failures; failing registration here would be worse.
             }
             catch (err) {
                 void normalizeError(err);

package/dist/features/blog/repository/blog.repository.js

@@ -72,10 +72,12 @@ class BlogRepository extends BaseRepository {
                 .collection(this.collection)
                 .doc(id)
                 .update({ [BLOG_POST_FIELDS.VIEWS]: increment(1) });
+            // Fire-and-forget analytics: a lost view increment changes nothing that
+            // renders and cannot usefully be retried, so it must never fail the blog
+            // post read that triggered it — the count is approximate by design.
         }
         catch (_err) {
             void normalizeError(_err);
-            // Fire-and-forget by design.
         }
     }
     async findRelated(category, excludeId, limit = 3) {

package/dist/features/cart/actions/cart-actions.js

@@ -14,6 +14,7 @@ import { getDefaultCurrency } from "../../../core/baseline-resolver";
 import { CART_LANE, activeLane, canAddNewItems, } from "../../../_internal/shared/checkout/lanes";
 import { CART_MAX_ITEMS } from "../../../constants/limits";
 import { getExpandedDecrements, validateCartItemStock, } from "../../../_internal/server/features/checkout/bundle-expansion";
+import { safeRead } from "../../../errors/safe-read";
 /**
  * Product documents don't always carry a denormalized `storeName` — the
  * create routes only set it when the caller explicitly passes one, so
@@ -26,7 +27,9 @@ import { getExpandedDecrements, validateCartItemStock, } from "../../../_interna
 async function resolveStoreName(storeId, candidate) {
     if (candidate)
         return candidate;
-    const store = await storeRepository.findById(storeId).catch(() => null);
+    const store = await safeRead(() => storeRepository.findById(storeId), {
+        route: "/cart", key: "stores.findById", fallback: null,
+    });
     return store?.storeName ?? storeId;
 }
 /**
@@ -102,7 +105,9 @@ export async function addGroupLineToCart(userId, input) {
     const cart = await assertCanAddNewItems(userId);
     // One batched read for the whole selection — capped at 20 above, so well
     // inside the per-request Firestore budget.
-    const docs = await Promise.all(members.map((m) => productRepository.findById(m.productId).catch(() => null)));
+    const docs = await Promise.all(members.map((m) => safeRead(() => productRepository.findById(m.productId), {
+        route: "/cart", key: "products.findById", fallback: null,
+    })));
     const productById = new Map(members.map((m, i) => [m.productId, docs[i]]));
     const { getListingRule } = await import("../../../_internal/shared/checkout/rules");
     const { ProductStatusValues } = await import("../../products/schemas/firestore");
@@ -209,14 +214,18 @@ export async function addGroupLineToCart(userId, input) {
 /** Is this product listed on that `groupedListings` document? */
 async function isGroupedListingMember(groupId, productId) {
     const { groupedListingsRepository } = await import("../../grouped/repository/grouped-listings.repository");
-    const group = await groupedListingsRepository.findById(groupId).catch(() => null);
+    const group = await safeRead(() => groupedListingsRepository.findById(groupId), {
+        route: "/cart", key: "groupedListings.findById", fallback: null,
+    });
     return Boolean(group?.productIds?.includes(productId));
 }
 /** Display name for the line. Falls back to the parent product's group title. */
 async function resolveGroupTitle(groupId, groupSource, sample) {
     if (groupSource === "grouped-listing") {
         const { groupedListingsRepository } = await import("../../grouped/repository/grouped-listings.repository");
-        const group = await groupedListingsRepository.findById(groupId).catch(() => null);
+        const group = await safeRead(() => groupedListingsRepository.findById(groupId), {
+            route: "/cart", key: "groupedListings.title", fallback: null,
+        });
         if (group?.title)
             return group.title;
     }

package/dist/features/cart/utils/pending-ops.js

@@ -72,10 +72,10 @@ function write(key, items) {
         return;
     try {
         localStorage.setItem(key, JSON.stringify(items));
+        // Quota exceeded or storage blocked. Losing pending ops costs a retry, never data: the cart is canonical in Firestore.
     }
     catch (_err) {
         void normalizeError(_err);
-        // storage quota exceeded — best effort
     }
 }
 function writeCartOps(items) {

package/dist/features/categories/components/BrandDetailPageView.js

@@ -16,24 +16,25 @@ import { listingTabCounts, } from "../../../_internal/server/features/products/l
 import { CATEGORY_PAGE_TABS } from "../../products/constants/listing-tabs";
 import { enabledCategoryTypes, enabledListingTypes } from "../../../_internal/shared/listing-types/feature-flags";
 import { siteSettingsRepository } from "../../../repositories";
+import { safeRead } from "../../../errors/safe-read";
 const __O = {
     hidden: "overflow-hidden",
 };
 export async function BrandDetailPageView({ slug, initialBrand }) {
+    // The brand IS this page's subject — a read failure must surface rather than
+    // render an anonymous, empty brand page. `undefined` still means "no such
+    // brand slug".
     const brand = (initialBrand ?? (await categoriesRepository
-        .getCategoryBySlug(slug)
-        .catch(() => undefined)));
+        .getCategoryBySlug(slug)) ?? undefined);
     const brandName = brand?.name;
     const [productsResult, tabCounts, allBundles, activeBrands, groupedListings, settings] = await Promise.all([
         brandName
-            ? productRepository
-                .list({
+            ? safeRead(() => productRepository.list({
                 filters: sieveAnd(sieveFilter("status", SIEVE_OP.EQ, "published"), sieveFilter("brand", SIEVE_OP.EQ, brandName), sieveFilter("listingType", SIEVE_OP.EQ, "standard")),
                 sorts: sortBy("createdAt", "DESC"),
                 page: 1,
                 pageSize: 24,
-            })
-                .catch(() => null)
+            }), { route: "/brands/[slug]", key: "brand.products", fallback: null })
             : Promise.resolve(null),
         // One count per tab, derived from CATEGORY_PAGE_TABS. Four of the nine tabs
         // (classifieds, digital codes, live, art) had no count at all and could
@@ -47,16 +48,31 @@ export async function BrandDetailPageView({ slug, initialBrand }) {
         // We pull all bundle categories and filter client-side by brandSlug —
         // no dedicated repository query needed at this catalog's bundle volume.
         brand?.slug
-            ? categoriesRepository
-                .listByType("bundle", { activeOnly: true, limit: 50 })
-                .catch(() => [])
+            ? safeRead(() => categoriesRepository.listByType("bundle", { activeOnly: true, limit: 50 }), { route: "/brands/[slug]", key: "brand.bundles", fallback: [] })
             : Promise.resolve([]),
         // Related brands — every other active brand row, excluding this one.
-        categoriesRepository.findActiveBrands().catch(() => []),
-        brand?.slug ? getGroupsForBrand(brand.slug).catch(() => []) : Promise.resolve([]),
+        // `as unknown` is load-bearing only because CategoryDocument.createdAt is a
+        // Date while CategoryItem.createdAt is a string — a pre-existing mismatch
+        // the old `.catch(() => [])` union happened to paper over.
+        safeRead(() => categoriesRepository.findActiveBrands(), {
+            route: "/brands/[slug]",
+            key: "brand.relatedBrands",
+            fallback: [],
+        }),
+        brand?.slug
+            ? safeRead(() => getGroupsForBrand(brand.slug), {
+                route: "/brands/[slug]",
+                key: "brand.groupedListings",
+                fallback: [],
+            })
+            : Promise.resolve([]),
         // Feature flags — accepted by BrandDetailTabs all along but never passed,
         // so a disabled listing type still showed its tab here.
-        siteSettingsRepository.findById("global").catch(() => null),
+        safeRead(() => siteSettingsRepository.findById("global"), {
+            route: "/brands/[slug]",
+            key: "brand.siteSettings",
+            fallback: null,
+        }),
     ]);
     const brandBundles = brand?.slug
         ? allBundles.filter((b) => b.brandSlug === brand.slug)

package/dist/features/categories/components/CategoryDetailPageView.js

@@ -15,14 +15,17 @@ import { listingTabCounts, } from "../../../_internal/server/features/products/l
 import { CATEGORY_PAGE_TABS } from "../../products/constants/listing-tabs";
 import { enabledCategoryTypes, enabledListingTypes } from "../../../_internal/shared/listing-types/feature-flags";
 import { siteSettingsRepository } from "../../../repositories";
+import { safeRead } from "../../../errors/safe-read";
 const __O = {
     hidden: "overflow-hidden",
     xAuto: "overflow-x-auto",
 };
 export async function CategoryDetailPageView({ slug }) {
-    const category = await categoriesRepository
-        .getCategoryBySlug(slug)
-        .catch(() => undefined);
+    // The category IS this page's subject — a read failure must surface rather
+    // than render an anonymous, empty category page. `undefined` still means
+    // "no such category slug".
+    const category = ((await categoriesRepository
+        .getCategoryBySlug(slug)) ?? undefined);
     // Products carry their FULL ancestor chain in `categorySlugs`, so matching on
     // this category's own id already returns the whole subtree — no descendant
     // expansion needed. Expanding it was also a latent outage: `categoriesIn` is
@@ -33,14 +36,12 @@ export async function CategoryDetailPageView({ slug }) {
     const categoriesIn = category?.id ? [category.id] : null;
     const [productsResult, tabCounts, bundlesResult, childCategories, rootSiblingCategories, groupedListings, settings] = await Promise.all([
         categoriesIn
-            ? productRepository
-                .list({
+            ? safeRead(() => productRepository.list({
                 filters: sieveAnd(sieveFilter("status", SIEVE_OP.EQ, "published"), sieveFilter("listingType", SIEVE_OP.EQ, "standard")),
                 sorts: sortBy("createdAt", "DESC"),
                 page: 1,
                 pageSize: 24,
-            }, { categoriesIn })
-                .catch(() => null)
+            }, { categoriesIn }), { route: "/categories/[slug]", key: "category.products", fallback: null })
             : Promise.resolve(null),
         // One count per tab, derived from CATEGORY_PAGE_TABS itself — so every
         // listing type is counted and a type with nothing in this category hides.
@@ -51,24 +52,40 @@ export async function CategoryDetailPageView({ slug }) {
         // SB-UNI-D — bundles fetched from the categories collection. We pull
         // all active bundle rows; the carousel filters by category affinity.
         categoriesIn
-            ? categoriesRepository
-                .listByType("bundle", { activeOnly: true, limit: 50 })
-                .catch(() => [])
+            ? safeRead(() => categoriesRepository.listByType("bundle", { activeOnly: true, limit: 50 }), { route: "/categories/[slug]", key: "category.bundles", fallback: [] })
             : Promise.resolve([]),
         category?.id
-            ? categoriesRepository.getChildren(category.id).catch(() => [])
+            ? safeRead(() => categoriesRepository.getChildren(category.id), {
+                route: "/categories/[slug]",
+                key: "category.children",
+                fallback: [],
+            })
             : Promise.resolve([]),
         // Related categories — every other category sharing this category's root
         // (siblings + cousins across the tree, up to the tier-0/1/2 depth the
         // catalog actually uses), not just direct children.
         category?.rootId
-            ? categoriesRepository.getCategoriesByRootId(category.rootId).catch(() => [])
+            ? safeRead(() => categoriesRepository.getCategoriesByRootId(category.rootId), {
+                route: "/categories/[slug]",
+                key: "category.rootSiblings",
+                fallback: [],
+            })
+            : Promise.resolve([]),
+        category?.slug
+            ? safeRead(() => getGroupsForCategory(category.slug), {
+                route: "/categories/[slug]",
+                key: "category.groupedListings",
+                fallback: [],
+            })
             : Promise.resolve([]),
-        category?.slug ? getGroupsForCategory(category.slug).catch(() => []) : Promise.resolve([]),
         // Listing/category-type feature flags. This page accepted the props all
         // along but never passed them, so an admin disabling a listing type still
         // saw its tab here while the store page correctly hid it.
-        siteSettingsRepository.findById("global").catch(() => null),
+        safeRead(() => siteSettingsRepository.findById("global"), {
+            route: "/categories/[slug]",
+            key: "category.siteSettings",
+            fallback: null,
+        }),
     ]);
     const relatedCategories = rootSiblingCategories.filter((c) => c.id !== category?.id && (!c.categoryType || c.categoryType === "category"));
     // Stores tab — stores whose storeCategory is this category or ANY descendant.
@@ -82,18 +99,18 @@ export async function CategoryDetailPageView({ slug }) {
     // which caps at 30 values, hence the chunking.
     const storeCategorySlugs = [
         slug,
-        ...(await categoriesRepository
-            .getDescendantIds(category?.id ?? "")
-            .catch(() => [])),
+        ...(await safeRead(() => categoriesRepository.getDescendantIds(category?.id ?? ""), {
+            route: "/categories/[slug]",
+            key: "category.descendantIds",
+            fallback: [],
+        })),
     ].filter(Boolean);
     const SLUG_CHUNK = 30;
     const slugChunks = [];
     for (let i = 0; i < storeCategorySlugs.length; i += SLUG_CHUNK) {
         slugChunks.push(storeCategorySlugs.slice(i, i + SLUG_CHUNK));
     }
-    const storeResults = await Promise.all(slugChunks.map((chunk) => storeRepository
-        .listStores({ filters: sieveFilter("storeCategory", SIEVE_OP.EQ, chunk.join("|")), page: 1, pageSize: 50 }, true)
-        .catch(() => null)));
+    const storeResults = await Promise.all(slugChunks.map((chunk) => safeRead(() => storeRepository.listStores({ filters: sieveFilter("storeCategory", SIEVE_OP.EQ, chunk.join("|")), page: 1, pageSize: 50 }, true), { route: "/categories/[slug]", key: "category.stores", fallback: null })));
     const seen = new Set();
     const categoryStores = storeResults
         .flatMap((r) => r?.items ?? [])