@mohasinac/appkit 4.30.18 → 4.31.0

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/catalogue/components/CatalogueItemEditorView.d.ts

@@ -1,3 +1,25 @@
+/**
+ * Add or edit an item in a user's personal catalogue.
+ *
+ * Fields come from `createCatalogueItemSchema`'s annotations. Three need a
+ * `renderers` entry: the photo list (a real uploader, not the generator's
+ * disabled placeholder), and the two taxonomy selects, which are searchable
+ * because 47 categories is well past the 5-option threshold.
+ *
+ * ## `categorySlugs` and `brandSlug` were declared, read, and never collected
+ *
+ * Both are inherited from `ProductDraftFields` and both are read by
+ * `product-from-item.ts`, which builds the marketplace listing when an item is
+ * promoted. The hand-rolled form had no control for either, so every promoted
+ * listing carried `categorySlugs: []` — and per the Category Tree rules a
+ * product with an empty chain is invisible on every category and brand page it
+ * should appear under. A schema field with a reader and no control is the
+ * inverse of a dead control, and just as silent.
+ *
+ * `mainImage` is `t1-derive` — the first photo, not a field anyone types. It
+ * renders as a read-only preview rather than a text box that could be desynced
+ * from the gallery it is supposed to mirror.
+ */
 import React from "react";
 import type { CatalogueItemDocument } from "../schemas/firestore";
 export interface CatalogueItemEditorViewProps {

package/dist/features/catalogue/components/CatalogueItemEditorView.js

@@ -1,60 +1,120 @@
 "use client";
-import { jsxs as _jsxs, jsx as _jsx } from "react/jsx-runtime";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * Add or edit an item in a user's personal catalogue.
+ *
+ * Fields come from `createCatalogueItemSchema`'s annotations. Three need a
+ * `renderers` entry: the photo list (a real uploader, not the generator's
+ * disabled placeholder), and the two taxonomy selects, which are searchable
+ * because 47 categories is well past the 5-option threshold.
+ *
+ * ## `categorySlugs` and `brandSlug` were declared, read, and never collected
+ *
+ * Both are inherited from `ProductDraftFields` and both are read by
+ * `product-from-item.ts`, which builds the marketplace listing when an item is
+ * promoted. The hand-rolled form had no control for either, so every promoted
+ * listing carried `categorySlugs: []` — and per the Category Tree rules a
+ * product with an empty chain is invisible on every category and brand page it
+ * should appear under. A schema field with a reader and no control is the
+ * inverse of a dead control, and just as silent.
+ *
+ * `mainImage` is `t1-derive` — the first photo, not a field anyone types. It
+ * renders as a read-only preview rather than a text box that could be desynced
+ * from the gallery it is supposed to mirror.
+ */
 import React from "react";
 import { useQueryClient } from "@tanstack/react-query";
 import { useApiMutation } from "@mohasinac/appkit/client";
-import { Alert, Button, FieldInput, FieldSelect, FieldTextarea, Form, Grid, Row, Span, Stack, Toggle } from "../../../ui";
-import { FormErrorSummary } from "../../../ui/forms";
-import { MediaUploadList } from "../../media/upload/MediaUploadList";
-import { useMediaUpload } from "../../media";
+import { ACCOUNT_ENDPOINTS, BRAND_ENDPOINTS, CATEGORY_ENDPOINTS } from "../../../constants/api-endpoints";
 import { apiClient } from "../../../http";
-import { ACCOUNT_ENDPOINTS } from "../../../constants/api-endpoints";
+import { Alert, PaginatedSelect, Stack } from "../../../ui";
+import { applyZodIssues } from "../../../ui/forms/apply-zod-issues";
+import { FormErrorSummary } from "../../../ui/forms/FormErrorSummary";
+import { FormShellContext, useFormShellState } from "../../../ui/forms/FormShell";
+import { buildSectionsFromSchema } from "../../shell/build-sections";
+import { SectionForm, useSectionFormNav } from "../../shell/SectionForm";
+import { useMediaUpload } from "../../media";
+import { MediaUploadList } from "../../media/upload/MediaUploadList";
 import { createCatalogueItemSchema } from "../schemas/validation";
-const CONDITION_OPTIONS = [
-    { label: "New", value: "new" },
-    { label: "Like new", value: "like_new" },
-    { label: "Good", value: "good" },
-    { label: "Fair", value: "fair" },
-    { label: "Poor", value: "poor" },
-    { label: "Used", value: "used" },
-    { label: "Refurbished", value: "refurbished" },
-];
+/** PUBLIC endpoints — this is a buyer surface; the admin ones would 403. */
+async function loadOptionsFrom(endpoint, query, page) {
+    const params = new URLSearchParams({ page: String(page), pageSize: "25" });
+    if (query)
+        params.set("q", query);
+    const res = await apiClient.get(`${endpoint}?${params.toString()}`);
+    const data = res ?? {};
+    return {
+        items: (data.items ?? []).map((c) => ({ value: c.id, label: c.name })),
+        hasMore: data.hasMore ?? false,
+    };
+}
+const loadCategoryOptions = (q, p) => loadOptionsFrom(CATEGORY_ENDPOINTS.LIST, q, p);
+const loadBrandOptions = (q, p) => loadOptionsFrom(BRAND_ENDPOINTS.LIST, q, p);
 export function CatalogueItemEditorView({ item, onSaved }) {
     const isCreate = !item;
     const queryClient = useQueryClient();
     const { upload } = useMediaUpload();
     const uploadIndexRef = React.useRef(0);
-    const [title, setTitle] = React.useState(item?.title ?? "");
-    const [description, setDescription] = React.useState(item?.description ?? "");
-    const [condition, setCondition] = React.useState(item?.condition ?? "");
-    const [price, setPrice] = React.useState(item?.price ? String(item.price) : "0");
-    const [quantity, setQuantity] = React.useState(String(item?.quantity ?? 1));
-    const [visibility, setVisibility] = React.useState(item?.visibility ?? "public");
-    const [images, setImages] = React.useState(item?.images ?? []);
-    const galleryFields = images.map((url) => ({ url, type: "image" }));
-    const handleUpload = async (file) => {
+    const [form, setForm] = React.useState({
+        title: item?.title ?? "",
+        description: item?.description ?? "",
+        condition: item?.condition ?? "",
+        quantity: item?.quantity ?? 1,
+        price: item?.price ?? 0,
+        images: item?.images ?? [],
+        mainImage: item?.mainImage ?? item?.images?.[0] ?? "",
+        categorySlugs: item?.categorySlugs ?? [],
+        brandSlug: item?.brandSlug ?? "",
+        visibility: item?.visibility ?? "public",
+    });
+    const handleUpload = React.useCallback(async (file) => {
         uploadIndexRef.current += 1;
         return upload(file, "catalogue", true, {
             type: "catalogue-image",
-            item: title || "item",
+            item: form.title || "item",
             index: uploadIndexRef.current,
         });
-    };
+    }, [upload, form.title]);
+    const sections = React.useMemo(() => buildSectionsFromSchema(createCatalogueItemSchema, {
+        renderers: {
+            images: ({ values, onChange }) => (_jsx(MediaUploadList, { label: "Photos", value: values.images.map((url) => ({ url, type: "image" })), onChange: (fields) => {
+                    const urls = fields.map((f) => f.url);
+                    // `mainImage` is derived, so it moves with the gallery rather
+                    // than pointing at a photo the user has since removed.
+                    onChange({ images: urls, mainImage: urls[0] ?? "" });
+                }, onUpload: handleUpload, accept: "image/*", maxItems: 8, helperText: "Photos older than 30 days must be refreshed before this item can be listed." })),
+            categorySlugs: ({ values, onChange }) => (
+            // Explicit `<string>`: with `multiple`, `value` is `V[]`, so an
+            // inferred V reads the array itself as the option type.
+            _jsx(PaginatedSelect, { multiple: true, value: values.categorySlugs, onChange: (v) => onChange({ categorySlugs: v ?? [] }), loadOptions: loadCategoryOptions, placeholder: "Search categories\u2026", searchPlaceholder: "Type a category name\u2026", noResultsText: "No categories found", ariaLabel: "Categories" })),
+            brandSlug: ({ values, onChange }) => (_jsx(PaginatedSelect, { value: values.brandSlug || null, onChange: (v) => onChange({ brandSlug: v ?? "" }), loadOptions: loadBrandOptions, placeholder: "Search brands\u2026", searchPlaceholder: "Type a brand name\u2026", noResultsText: "No brands found", ariaLabel: "Brand" })),
+        },
+    }), [handleUpload]);
+    const nav = useSectionFormNav(sections, form, { scope: "user:catalogue-item" });
+    const { shellCtx, setFieldError, clearErrors } = useFormShellState(createCatalogueItemSchema, {
+        sections: nav.sectionMeta,
+        onGoToSection: nav.goToSection,
+        fieldToSectionIndex: nav.fieldToSectionIndex,
+    });
     const saveMutation = useApiMutation({
         successMessage: isCreate ? "Added to your catalogue" : "Catalogue item updated",
+        errorMessage: isCreate ? "Could not add this item." : "Could not save your changes.",
         mutationFn: async () => {
             const payload = {
-                title,
-                description: description || undefined,
-                condition: condition || undefined,
-                price: Math.round(Number(price) * 100) / 100,
-                quantity: Number(quantity),
-                visibility,
-                images,
-                mainImage: images[0],
+                title: form.title,
+                description: form.description || undefined,
+                condition: form.condition || undefined,
+                price: Math.round(Number(form.price) * 100) / 100,
+                quantity: Number(form.quantity),
+                visibility: form.visibility,
+                images: form.images,
+                mainImage: form.images[0],
+                categorySlugs: form.categorySlugs,
+                brandSlug: form.brandSlug || undefined,
             };
-            if (isCreate)
+            if (isCreate) {
                 return apiClient.post(ACCOUNT_ENDPOINTS.CATALOGUE, payload);
+            }
             return apiClient.patch(ACCOUNT_ENDPOINTS.CATALOGUE_BY_ID(item.id), payload);
         },
         onSuccess: (saved) => {
@@ -62,21 +122,21 @@ export function CatalogueItemEditorView({ item, onSaved }) {
             onSaved?.(saved.id);
         },
     });
-    return (_jsx(Form, { schema: createCatalogueItemSchema, spacing: "md", children: ({ setFieldError, markSubmitAttempted }) => (_jsxs(Stack, { gap: "md", children: [item?.listingStatus && item.listingStatus !== "not_listed" && (_jsxs(Alert, { variant: "info", children: ["This item is ", item.listingStatus.replace(/_/g, " "), item.listingStatus === "rejected" && item.rejectionReason ? `: ${item.rejectionReason}` : "."] })), _jsxs(Grid, { cols: 2, gap: "md", children: [_jsx(FieldInput, { name: "title", label: "Title", required: true, value: title, onChange: setTitle }), _jsx(FieldSelect, { name: "condition", label: "Condition", value: condition, onChange: setCondition, options: CONDITION_OPTIONS }), _jsx(FieldInput, { name: "price", label: "Estimated resale price (\u20B9)", type: "number", min: "0", value: price, onChange: setPrice }), _jsx(FieldInput, { name: "quantity", label: "Quantity", type: "number", min: "1", value: quantity, onChange: setQuantity })] }), _jsx(FieldTextarea, { name: "description", label: "Description", value: description, onChange: setDescription, rows: 3 }), _jsx(MediaUploadList, { label: "Photos", value: galleryFields, onChange: (fields) => setImages(fields.map((f) => f.url)), onUpload: handleUpload, accept: "image/*", maxItems: 8, helperText: "Photos older than 30 days must be refreshed before this item can be listed." }), _jsxs(Row, { gap: "sm", align: "center", children: [_jsx(Toggle, { checked: visibility === "public", onChange: (checked) => setVisibility(checked ? "public" : "private"), size: "sm" }), _jsx(Span, { children: visibility === "public" ? "Public — visible on your profile" : "Private — only you can see it" })] }), _jsx(FormErrorSummary, {}), _jsx(Button, { type: "button", isLoading: saveMutation.isPending, onClick: () => {
-                        // type="button" — no native submit, so unhide the summary here.
-                        markSubmitAttempted();
-                        const parsed = createCatalogueItemSchema.safeParse({
-                            title,
-                            images,
-                            price: Math.round(Number(price) * 100) / 100,
-                            quantity: Number(quantity),
-                            visibility,
-                        });
-                        if (!parsed.success) {
-                            for (const issue of parsed.error.issues)
-                                setFieldError(String(issue.path[0]), issue.message);
-                            return;
-                        }
-                        saveMutation.mutate();
-                    }, children: isCreate ? "Add to Catalogue" : "Save Changes" })] })) }));
+    const onSubmit = () => {
+        clearErrors();
+        const parsed = createCatalogueItemSchema.safeParse({
+            ...form,
+            price: Math.round(Number(form.price) * 100) / 100,
+            quantity: Number(form.quantity),
+            brandSlug: form.brandSlug || undefined,
+        });
+        if (!parsed.success) {
+            applyZodIssues(parsed.error.issues, setFieldError);
+            return;
+        }
+        saveMutation.mutate();
+    };
+    return (_jsxs(Stack, { gap: "md", children: [item?.listingStatus && item.listingStatus !== "not_listed" && (_jsxs(Alert, { variant: "info", children: ["This item is ", item.listingStatus.replace(/_/g, " "), item.listingStatus === "rejected" && item.rejectionReason
+                        ? `: ${item.rejectionReason}`
+                        : "."] })), _jsxs(FormShellContext.Provider, { value: shellCtx, children: [_jsx(FormErrorSummary, {}), _jsx(SectionForm, { sections: sections, values: form, onChange: (partial) => setForm((prev) => Object.assign({}, prev, partial)), onSubmit: onSubmit, schema: createCatalogueItemSchema, openIds: nav.openIds, onOpenChange: nav.setOpenIds, isLoading: saveMutation.isPending, submitLabel: isCreate ? "Add to Catalogue" : "Save Changes" })] })] }));
 }

package/dist/features/catalogue/schemas/validation.d.ts

@@ -2,13 +2,13 @@ import { z } from "zod";
 export declare const createCatalogueItemSchema: z.ZodObject<{
     title: z.ZodString;
     description: z.ZodOptional<z.ZodString>;
+    condition: z.ZodOptional<z.ZodEnum<["new", "like_new", "good", "fair", "poor", "used", "refurbished", "broken", "graded"]>>;
+    quantity: z.ZodDefault<z.ZodNumber>;
     images: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
     mainImage: z.ZodOptional<z.ZodString>;
-    condition: z.ZodOptional<z.ZodEnum<["new", "like_new", "good", "fair", "poor", "used", "refurbished", "broken", "graded"]>>;
     categorySlugs: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
     brandSlug: z.ZodOptional<z.ZodString>;
     price: z.ZodOptional<z.ZodNumber>;
-    quantity: z.ZodDefault<z.ZodNumber>;
     visibility: z.ZodDefault<z.ZodEnum<["public", "private"]>>;
 }, "strip", z.ZodTypeAny, {
     title: string;
@@ -36,13 +36,13 @@ export declare const createCatalogueItemSchema: z.ZodObject<{
 export declare const updateCatalogueItemSchema: z.ZodObject<{
     title: z.ZodOptional<z.ZodString>;
     description: z.ZodOptional<z.ZodOptional<z.ZodString>>;
+    condition: z.ZodOptional<z.ZodOptional<z.ZodEnum<["new", "like_new", "good", "fair", "poor", "used", "refurbished", "broken", "graded"]>>>;
+    quantity: z.ZodOptional<z.ZodDefault<z.ZodNumber>>;
     images: z.ZodOptional<z.ZodDefault<z.ZodArray<z.ZodString, "many">>>;
     mainImage: z.ZodOptional<z.ZodOptional<z.ZodString>>;
-    condition: z.ZodOptional<z.ZodOptional<z.ZodEnum<["new", "like_new", "good", "fair", "poor", "used", "refurbished", "broken", "graded"]>>>;
     categorySlugs: z.ZodOptional<z.ZodOptional<z.ZodArray<z.ZodString, "many">>>;
     brandSlug: z.ZodOptional<z.ZodOptional<z.ZodString>>;
     price: z.ZodOptional<z.ZodOptional<z.ZodNumber>>;
-    quantity: z.ZodOptional<z.ZodDefault<z.ZodNumber>>;
     visibility: z.ZodOptional<z.ZodDefault<z.ZodEnum<["public", "private"]>>>;
 }, "strip", z.ZodTypeAny, {
     title?: string | undefined;

package/dist/features/catalogue/schemas/validation.js

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { annotate } from "../../shell/field-ui-meta";
 const productConditionSchema = z.enum([
     "new",
     "like_new",
@@ -11,15 +12,51 @@ const productConditionSchema = z.enum([
     "graded",
 ]);
 export const createCatalogueItemSchema = z.object({
-    title: z.string().min(1, "Title is required"),
-    description: z.string().optional(),
-    images: z.array(z.string()).default([]),
-    mainImage: z.string().optional(),
-    condition: productConditionSchema.optional(),
-    categorySlugs: z.array(z.string()).optional(),
-    brandSlug: z.string().optional(),
-    price: z.number().min(0).optional(),
-    quantity: z.number().int().min(1).default(1),
-    visibility: z.enum(["public", "private"]).default("public"),
+    title: annotate(z.string().min(1, "Title is required"), {
+        section: "basics", sectionLabel: "Item", sectionRequired: true,
+        order: 1, row: "full", label: "Title",
+    }),
+    description: annotate(z.string().optional(), {
+        section: "basics", order: 2, row: "full", kind: "textarea", label: "Description",
+    }),
+    condition: annotate(productConditionSchema.optional(), {
+        section: "basics", order: 3, row: "pair", kind: "select", label: "Condition",
+    }),
+    quantity: annotate(z.number().int().min(1).default(1), {
+        section: "basics", order: 4, row: "pair", kind: "number", label: "Quantity",
+    }),
+    /*
+     * `kind: "media"` is inferred from the field NAME (field-ui-meta.ts:336),
+     * which also sets `sectionKeepMounted` — mandatory here, because a collapsed
+     * section unmounts and would discard an in-flight upload. Declared anyway so
+     * the section id and order are not left to inference.
+     */
+    images: annotate(z.array(z.string()).default([]), {
+        section: "media", sectionLabel: "Photos", order: 1, row: "full", kind: "media",
+        sectionKeepMounted: true, label: "Photos",
+    }),
+    /*
+     * Derived from `images[0]`, never typed. Rendering it as an editable box
+     * lets a user point it at a photo they have since removed from the gallery —
+     * the field would then name an image that does not exist on the item.
+     */
+    mainImage: annotate(z.string().optional(), {
+        section: "media", order: 2, row: "full", kind: "media", label: "Main photo",
+        derived: true, tier: "t1-derive", help: "The first photo in the gallery.",
+    }),
+    categorySlugs: annotate(z.array(z.string()).optional(), {
+        section: "classification", sectionLabel: "Filing", order: 1, row: "pair",
+        label: "Categories",
+    }),
+    brandSlug: annotate(z.string().optional(), {
+        section: "classification", order: 2, row: "pair", kind: "select", label: "Brand",
+    }),
+    price: annotate(z.number().min(0).optional(), {
+        section: "pricing", sectionLabel: "Value", order: 1, row: "pair", kind: "number",
+        label: "Estimated value (₹)",
+    }),
+    visibility: annotate(z.enum(["public", "private"]).default("public"), {
+        section: "visibility", order: 1, row: "pair", kind: "select", label: "Visibility",
+    }),
 });
 export const updateCatalogueItemSchema = createCatalogueItemSchema.partial();

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 ?? [])

package/dist/features/categories/repository/categories.repository.js

@@ -480,10 +480,12 @@ export class CategoriesRepository extends BaseRepository {
                 .collection(this.collection)
                 .doc(categoryId)
                 .update({ [CATEGORY_FIELDS.VIEW_COUNT]: increment(1) });
+            // Fire-and-forget analytics: a lost view increment changes nothing that
+            // renders, so it must never break the category read path it rides along
+            // with — the count is approximate by design.
         }
         catch (_err) {
             void normalizeError(_err);
-            // View analytics must not break category read path.
         }
     }
     generateSublistingId(name) {