@mohasinac/appkit 4.56.0 → 4.58.0

package/dist/features/homepage/components/ShopByCategorySection.js

@@ -4,26 +4,39 @@ import { useState } from "react";
 import Image from "next/image.js";
 import Link from "next/link.js";
 import { THEMED_TEXT_PRIMARY } from "../../../_internal/shared/styles/themed.js";
-import { Button, Div, Heading, HorizontalScroller, Row, Section, Span, Stack, Text } from "../../../ui/index.js";
+import { Button, Div, Heading, HorizontalScroller, POSTER_CLASS, Row, Section, Span, Text, } from "../../../ui/index.js";
 import { ROUTES } from "../../../next/routing/route-map.js";
 import { resolveMediaUrl } from "../../../utils/media-url.js";
 import { useTopCategories } from "../hooks/useTopCategories.js";
 import { CAROUSEL_PER_VIEW } from "../constants/carousel-per-view.js";
-const __P = {
-    p3: "p-[var(--appkit-space-3)]",
-};
-const __O = {
-    hidden: "overflow-hidden",
-};
 function isImageUrl(s) {
     return s.startsWith("http") || s.startsWith("/") || s.startsWith("data:");
 }
+/**
+ * One category tile.
+ *
+ * 🛑 Image-LED, not image-on-top-of-a-body. The previous shape was a 16:9 crop
+ * stacked over a white block holding an icon square, the name, a count and a
+ * "Browse category →" line — four separate type sizes and a redundant CTA on a
+ * tile that is already entirely a link. It also letterboxed the artwork: every
+ * generation cover is portrait key art, so `aspect-video` cropped it to a
+ * horizontal band through the middle.
+ *
+ * Now it is the same `PosterCard` the systems matrix uses, so the two bands on
+ * the homepage read as one system rather than two designs.
+ */
 function CategoryChip({ category }) {
     const iconSrc = category.display?.icon;
     const coverImage = category.display?.coverImage;
-    const initial = category.name[0]?.toUpperCase() ?? "?";
+    const resolvedCover = coverImage && isImageUrl(coverImage) ? resolveMediaUrl(coverImage) : undefined;
     const productCount = category.metrics?.totalProductCount ?? category.metrics?.productCount ?? 0;
-    return (_jsxs(Link, { href: ROUTES.PUBLIC.CATEGORY_DETAIL(category.slug), className: "group flex w-full min-h-[180px] sm:min-h-[220px] flex-col overflow-hidden rounded-xl border bg-[var(--appkit-color-surface)] shadow-sm transition-all hover:border-primary-300 hover:shadow-md border-[var(--appkit-color-border)] bg-[var(--appkit-color-surface)] dark:hover:border-primary-600", children: [coverImage && isImageUrl(coverImage) ? (_jsx(Div, { className: `aspect-video w-full ${__O.hidden}`, surface: "subtle", children: _jsx(Image, { src: resolveMediaUrl(coverImage), alt: category.name, width: 320, height: 180, className: "h-full w-full object-cover transition-transform duration-300 group-hover:scale-105" }) })) : (_jsx(Div, { surface: "muted", className: "aspect-video w-full" })), _jsxs(Stack, { className: `flex-1 ${__P.p3} text-left`, children: [_jsx(Row, { textWeight: "bold", textSize: "sm", className: "mb-2 h-9 w-9 bg-primary-100 text-primary-700 dark:bg-primary-900 dark:text-primary-300", align: "center", justify: "center", rounded: "lg", children: iconSrc && isImageUrl(iconSrc) ? (_jsx(Image, { src: resolveMediaUrl(iconSrc), alt: "", width: 24, height: 24, className: "h-6 w-6 rounded object-cover", "aria-hidden": true })) : iconSrc ? (_jsx(Span, { size: "lg", "aria-hidden": "true", className: "leading-none", children: iconSrc })) : (initial) }), _jsx(Text, { size: "sm", weight: "semibold", color: "primary", truncate: 2, children: category.name }), _jsxs(Text, { className: "mt-1", color: "muted", size: "xs", children: [productCount.toLocaleString(), " items"] }), _jsx(Text, { className: "mt-auto text-primary dark:text-primary-400 pt-[0.75rem]", size: "xs", weight: "medium", children: "Browse category \u2192" })] })] }));
+    /*
+     * `display.icon` holds an EMOJI in the seed and a URL in other writers —
+     * the ambiguity `resolveTaxonomyVisual` exists for. Only the emoji form is
+     * used as an eyebrow glyph here; a URL would print as raw text.
+     */
+    const emoji = iconSrc && !isImageUrl(iconSrc) ? iconSrc : undefined;
+    return (_jsxs(Link, { href: ROUTES.PUBLIC.CATEGORY_DETAIL(category.slug), className: `${POSTER_CLASS.root} ${POSTER_CLASS.compact} w-full`, children: [resolvedCover ? (_jsx(Div, { className: POSTER_CLASS.media, children: _jsx(Image, { src: resolvedCover, alt: "", fill: true, sizes: "(min-width: 1024px) 20rem, (min-width: 640px) 45vw, 80vw", className: "h-full w-full object-cover" }) })) : null, _jsx(Div, { className: POSTER_CLASS.scrim, "aria-hidden": "true" }), _jsxs(Div, { className: POSTER_CLASS.body, children: [emoji && (_jsx(Span, { className: POSTER_CLASS.eyebrow, "aria-hidden": "true", children: emoji })), _jsx(Span, { className: POSTER_CLASS.title, children: category.name }), _jsxs(Span, { className: POSTER_CLASS.meta, children: [productCount.toLocaleString(), " items"] })] })] }));
 }
 const CTA_CLASSES = {
     filled: "rounded-lg bg-[var(--appkit-color-primary)] px-[var(--appkit-space-5)] py-[var(--appkit-space-2)] text-[length:var(--appkit-text-sm)] font-semibold text-white hover:opacity-90",
@@ -69,5 +82,5 @@ export function ShopByCategorySection({ title = "Shop by Category", subtitle, li
                             if (!cat)
                                 return null;
                             return (_jsx(FilterChip, { label: cat.name, active: activeFilter === id, onClick: () => setActiveFilter(activeFilter === id ? "all" : id) }, id));
-                        })] })), isLoading ? (_jsx(Div, { layout: "flex", gap: "3", className: `${__O.hidden} px-[0.25rem]`, children: Array.from({ length: 6 }).map((_, i) => (_jsx(Div, { className: "flex-none h-[104px] w-[108px] animate-pulse", surface: "subtle", rounded: "xl" }, i))) })) : (_jsx(HorizontalScroller, { items: categories, renderItem: (cat) => _jsx(CategoryChip, { category: cat }), perView: CAROUSEL_PER_VIEW.standard, gap: 16, keyExtractor: (cat) => cat.id, autoScroll: autoScroll, autoScrollInterval: scrollInterval, showArrows: true, snapToItems: true, showScrollbar: false, loop: loop, pauseOnHover: true })), cta && !isLoading && (_jsx(Div, { className: "mt-6 text-left", children: _jsx(Link, { href: cta.href, className: CTA_CLASSES[cta.variant], children: cta.label }) })), !cta && viewMoreHref && !isLoading && (_jsx(Div, { className: "mt-6 text-left", children: _jsx(Link, { href: viewMoreHref, className: "inline-flex items-center gap-[0.375rem] rounded-[var(--appkit-radius-md)] px-[var(--appkit-space-3)] py-[var(--appkit-space-1)] text-[length:var(--appkit-text-sm)] font-semibold transition-colors bg-primary text-white hover:bg-primary-600", children: viewMoreLabel }) }))] }) }));
+                        })] })), isLoading ? (_jsx(Div, { layout: "flex", gap: "3", overflow: "hidden", className: "px-[0.25rem]", children: Array.from({ length: 6 }).map((_, i) => (_jsx(Div, { className: "flex-none h-[104px] w-[108px] animate-pulse", surface: "subtle", rounded: "xl" }, i))) })) : (_jsx(HorizontalScroller, { items: categories, renderItem: (cat) => _jsx(CategoryChip, { category: cat }), perView: CAROUSEL_PER_VIEW.standard, gap: 16, keyExtractor: (cat) => cat.id, autoScroll: autoScroll, autoScrollInterval: scrollInterval, showArrows: true, snapToItems: true, showScrollbar: false, loop: loop, pauseOnHover: true })), cta && !isLoading && (_jsx(Div, { className: "mt-6 text-left", children: _jsx(Link, { href: cta.href, className: CTA_CLASSES[cta.variant], children: cta.label }) })), !cta && viewMoreHref && !isLoading && (_jsx(Div, { className: "mt-6 text-left", children: _jsx(Link, { href: viewMoreHref, className: "inline-flex items-center gap-[0.375rem] rounded-[var(--appkit-radius-md)] px-[var(--appkit-space-3)] py-[var(--appkit-space-1)] text-[length:var(--appkit-text-sm)] font-semibold transition-colors bg-primary text-white hover:bg-primary-600", children: viewMoreLabel }) }))] }) }));
 }

package/dist/features/homepage/lib/section-renderer.js

@@ -48,6 +48,7 @@ import { CollectionCardsSection } from "../components/CollectionCardsSection.js"
 import { HowItWorksSection } from "../components/HowItWorksSection.js";
 import { TestimonialsCarousel } from "../components/TestimonialsCarousel.js";
 import { PromoGrid } from "../components/PromoGrid.js";
+import { OwnerQuickActions } from "../../admin/components/OwnerQuickActions.js";
 const AD_SLOT_MAP = {
     carousel: "afterHero",
     products: "afterFeaturedProducts",
@@ -433,6 +434,6 @@ export function renderSection(section, adSlots, newsletterFormSlot, faqItems, sl
     if (!sectionElement)
         return null;
     const adSlotKey = AD_SLOT_MAP[section.type];
-    return (_jsxs(React.Fragment, { children: [_jsx(HomepageSectionBoundary, { sectionId: section.id, sectionType: section.type, children: sectionElement }), adSlots && adSlotKey !== undefined && adSlotKey in adSlots && adSlots[adSlotKey]] }, section.id));
+    return (_jsxs(React.Fragment, { children: [_jsx(OwnerQuickActions, { resource: "SECTION", placement: "detail", className: "justify-end", recordLabel: section.type, editHref: String(ROUTES.ADMIN.SECTIONS) }), _jsx(HomepageSectionBoundary, { sectionId: section.id, sectionType: section.type, children: sectionElement }), adSlots && adSlotKey !== undefined && adSlotKey in adSlots && adSlots[adSlotKey]] }, section.id));
 }
 export { AnnouncementBar, hashBannerMessage };

package/dist/features/homepage/schemas/index.d.ts

@@ -215,15 +215,15 @@ export declare const carouselCardSchema: z.ZodObject<{
         description?: string | undefined;
         textColor?: string | undefined;
         textAlign?: "center" | "left" | "right" | undefined;
-        subtitle?: string | undefined;
         eyebrow?: string | undefined;
+        subtitle?: string | undefined;
     }, {
         title?: string | undefined;
         description?: string | undefined;
         textColor?: string | undefined;
         textAlign?: "center" | "left" | "right" | undefined;
-        subtitle?: string | undefined;
         eyebrow?: string | undefined;
+        subtitle?: string | undefined;
     }>>;
     buttons: z.ZodOptional<z.ZodArray<z.ZodObject<{
         id: z.ZodOptional<z.ZodString>;
@@ -282,8 +282,8 @@ export declare const carouselCardSchema: z.ZodObject<{
         description?: string | undefined;
         textColor?: string | undefined;
         textAlign?: "center" | "left" | "right" | undefined;
-        subtitle?: string | undefined;
         eyebrow?: string | undefined;
+        subtitle?: string | undefined;
     } | undefined;
     hover?: {
         effect: "none" | "color" | "scale" | "glow";
@@ -323,8 +323,8 @@ export declare const carouselCardSchema: z.ZodObject<{
         description?: string | undefined;
         textColor?: string | undefined;
         textAlign?: "center" | "left" | "right" | undefined;
-        subtitle?: string | undefined;
         eyebrow?: string | undefined;
+        subtitle?: string | undefined;
     } | undefined;
     hover?: {
         effect: "none" | "color" | "scale" | "glow";
@@ -555,15 +555,15 @@ export declare const carouselSlideFirestoreSchema: z.ZodObject<{
             description?: string | undefined;
             textColor?: string | undefined;
             textAlign?: "center" | "left" | "right" | undefined;
-            subtitle?: string | undefined;
             eyebrow?: string | undefined;
+            subtitle?: string | undefined;
         }, {
             title?: string | undefined;
             description?: string | undefined;
             textColor?: string | undefined;
             textAlign?: "center" | "left" | "right" | undefined;
-            subtitle?: string | undefined;
             eyebrow?: string | undefined;
+            subtitle?: string | undefined;
         }>>;
         buttons: z.ZodOptional<z.ZodArray<z.ZodObject<{
             id: z.ZodOptional<z.ZodString>;
@@ -622,8 +622,8 @@ export declare const carouselSlideFirestoreSchema: z.ZodObject<{
             description?: string | undefined;
             textColor?: string | undefined;
             textAlign?: "center" | "left" | "right" | undefined;
-            subtitle?: string | undefined;
             eyebrow?: string | undefined;
+            subtitle?: string | undefined;
         } | undefined;
         hover?: {
             effect: "none" | "color" | "scale" | "glow";
@@ -663,8 +663,8 @@ export declare const carouselSlideFirestoreSchema: z.ZodObject<{
             description?: string | undefined;
             textColor?: string | undefined;
             textAlign?: "center" | "left" | "right" | undefined;
-            subtitle?: string | undefined;
             eyebrow?: string | undefined;
+            subtitle?: string | undefined;
         } | undefined;
         hover?: {
             effect: "none" | "color" | "scale" | "glow";
@@ -802,8 +802,8 @@ export declare const carouselSlideFirestoreSchema: z.ZodObject<{
             description?: string | undefined;
             textColor?: string | undefined;
             textAlign?: "center" | "left" | "right" | undefined;
-            subtitle?: string | undefined;
             eyebrow?: string | undefined;
+            subtitle?: string | undefined;
         } | undefined;
         hover?: {
             effect: "none" | "color" | "scale" | "glow";
@@ -911,8 +911,8 @@ export declare const carouselSlideFirestoreSchema: z.ZodObject<{
             description?: string | undefined;
             textColor?: string | undefined;
             textAlign?: "center" | "left" | "right" | undefined;
-            subtitle?: string | undefined;
             eyebrow?: string | undefined;
+            subtitle?: string | undefined;
         } | undefined;
         hover?: {
             effect: "none" | "color" | "scale" | "glow";

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

@@ -0,0 +1,19 @@
+import React from "react";
+import type { EmiInstallment } from "../schemas/firestore";
+export interface EmiInstallmentsPanelProps {
+    orderId: string;
+    installments: readonly EmiInstallment[];
+    /** Sum of unpaid instalments, as recorded on the order. */
+    remainingBalance?: number;
+    currency?: string;
+    /**
+     * Submits one instalment. Supplied by the consumer so this component does
+     * no fetching of its own — the same slot shape the rest of the orders
+     * feature uses.
+     */
+    onSubmit: (input: {
+        installmentIndex: number;
+        transactionId: string;
+    }) => Promise<void>;
+}
+export declare function EmiInstallmentsPanel({ orderId, installments, remainingBalance, currency, onSubmit, }: EmiInstallmentsPanelProps): React.JSX.Element;

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

@@ -0,0 +1,57 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useState } from "react";
+import { Badge, Button, Div, Form, Row, Stack, Text, useToast } from "../../../ui/index.js";
+import { FieldInput } from "../../../ui/forms/index.js";
+import { formatCurrency } from "../../../utils/number.formatter.js";
+import { normalizeError } from "../../../errors/normalize.js";
+function stateOf(i) {
+    if (i.status === "paid")
+        return "paid";
+    // A reference the buyer submitted but nobody has confirmed. The status
+    // field cannot express this: an instalment is created "pending" and stays
+    // "pending" until it is paid, so the presence of a reference is the signal.
+    if (i.transactionId)
+        return "awaiting-review";
+    return "payable";
+}
+const STATE_LABEL = {
+    paid: "Paid",
+    "awaiting-review": "Awaiting confirmation",
+    payable: "Due",
+};
+export function EmiInstallmentsPanel({ orderId, installments, remainingBalance, currency = "INR", onSubmit, }) {
+    const { showToast } = useToast();
+    const [openIndex, setOpenIndex] = useState(null);
+    const [reference, setReference] = useState("");
+    const [isSubmitting, setIsSubmitting] = useState(false);
+    const money = (value) => formatCurrency(value, currency);
+    const ordered = [...installments].sort((a, b) => a.index - b.index);
+    const outstanding = ordered.filter((i) => i.status !== "paid").length;
+    const submit = async (index) => {
+        setIsSubmitting(true);
+        try {
+            await onSubmit({ installmentIndex: index, transactionId: reference.trim() });
+            showToast("Payment reference submitted — the seller will confirm it.", "success");
+            setOpenIndex(null);
+            setReference("");
+        }
+        catch (err) {
+            void normalizeError(err);
+            // The action's own message is surfaced by the caller's error mapping;
+            // this only has to stop the panel pretending the submission landed.
+            showToast("Couldn't submit that payment. Please try again.", "error");
+        }
+        finally {
+            setIsSubmitting(false);
+        }
+    };
+    return (_jsx(Div, { surface: "card", border: "default", rounded: "lg", padding: "md", children: _jsxs(Stack, { gap: "sm", children: [_jsxs(Row, { align: "center", justify: "between", gap: "sm", children: [_jsx(Text, { weight: "semibold", children: "Your EMI plan" }), remainingBalance !== undefined && remainingBalance > 0 && (_jsxs(Text, { size: "sm", color: "muted", children: [money(remainingBalance), " outstanding across ", outstanding, " instalment", outstanding === 1 ? "" : "s"] }))] }), _jsx(Text, { size: "xs", color: "muted", children: "You can pay any instalment whenever you like, including ahead of its due date \u2014 paying early settles the plan sooner and does not cost more." }), _jsx(Stack, { gap: "xs", children: ordered.map((inst) => {
+                        const state = stateOf(inst);
+                        const due = inst.dueDate ? new Date(inst.dueDate) : null;
+                        return (_jsxs(Div, { border: "default", rounded: "md", padding: "sm", children: [_jsxs(Row, { align: "center", justify: "between", gap: "sm", className: "min-w-0", children: [_jsxs(Stack, { gap: "xs", className: "min-w-0", children: [_jsxs(Text, { size: "sm", weight: "medium", children: ["Instalment ", inst.index, " \u00B7 ", money(inst.amount)] }), _jsx(Text, { size: "xs", color: "muted", children: due ? `Due ${due.toLocaleDateString()}` : "No due date recorded" })] }), _jsxs(Row, { align: "center", gap: "xs", className: "flex-shrink-0", children: [_jsx(Badge, { variant: state === "paid" ? "success" : state === "awaiting-review" ? "warning" : "default", children: STATE_LABEL[state] }), state === "payable" && (_jsx(Button, { type: "button", size: "sm", variant: "secondary", onClick: () => {
+                                                        setOpenIndex(openIndex === inst.index ? null : inst.index);
+                                                        setReference("");
+                                                    }, children: openIndex === inst.index ? "Cancel" : "Pay now" }))] })] }), openIndex === inst.index && (_jsx(Div, { className: "mt-3", children: _jsx(Form, { onSubmit: (e) => e.preventDefault(), children: () => (_jsxs(Stack, { gap: "sm", children: [_jsxs(Text, { size: "xs", color: "muted", children: ["Transfer ", money(inst.amount), " to the seller, then enter the UTR or reference number so they can confirm it."] }), _jsx(FieldInput, { name: `emi-reference-${orderId}-${inst.index}`, label: "UTR / reference number", required: true, value: reference, onChange: setReference }), _jsx(Button, { type: "submit", size: "sm", isLoading: isSubmitting, disabled: reference.trim().length === 0 || isSubmitting, onClick: () => { void submit(inst.index); }, children: "Submit payment reference" })] })) }) }))] }, inst.index));
+                    }) })] }) }));
+}

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

@@ -14,3 +14,4 @@ export { RefundRequestView } from "./RefundRequestView";
 export type { RefundRequestViewProps } from "./RefundRequestView";
 export { YourPurchaseStrip } from "./YourPurchaseStrip";
 export type { YourPurchaseStripProps, PurchaseContext } from "./YourPurchaseStrip";
+export { EmiInstallmentsPanel, type EmiInstallmentsPanelProps, } from "./EmiInstallmentsPanel";

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

@@ -7,3 +7,4 @@ export { OrderStatusTimeline } from "./OrderStatusTimeline.js";
 export { RefundHistoryTable } from "./RefundHistoryTable.js";
 export { RefundRequestView } from "./RefundRequestView.js";
 export { YourPurchaseStrip } from "./YourPurchaseStrip.js";
+export { EmiInstallmentsPanel, } from "./EmiInstallmentsPanel.js";

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

@@ -614,6 +614,7 @@ export declare const orderFirestoreSchema: z.ZodObject<{
     } | undefined;
     offerId?: string | undefined;
     orderType?: string | undefined;
+    isNonRefundable?: boolean | undefined;
     imageUrls?: string[] | undefined;
     refundFeeDeducted?: number | undefined;
     refundNetAmount?: number | undefined;
@@ -650,7 +651,6 @@ export declare const orderFirestoreSchema: z.ZodObject<{
     }[] | undefined;
     emiRemainingBalance?: number | undefined;
     emiComplete?: boolean | undefined;
-    isNonRefundable?: boolean | undefined;
     paymentBatchId?: string | undefined;
     refunds?: {
         type: "full" | "partial";
@@ -762,6 +762,7 @@ export declare const orderFirestoreSchema: z.ZodObject<{
     } | undefined;
     offerId?: string | undefined;
     orderType?: string | undefined;
+    isNonRefundable?: boolean | undefined;
     imageUrls?: string[] | undefined;
     refundFeeDeducted?: number | undefined;
     refundNetAmount?: number | undefined;
@@ -798,7 +799,6 @@ export declare const orderFirestoreSchema: z.ZodObject<{
     }[] | undefined;
     emiRemainingBalance?: number | undefined;
     emiComplete?: boolean | undefined;
-    isNonRefundable?: boolean | undefined;
     paymentBatchId?: string | undefined;
     refunds?: {
         type: "full" | "partial";

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

@@ -1,3 +1,4 @@
+import type { EmiInstallment } from "../schemas/firestore";
 import type { ListingType } from "../../products/types/index";
 import type { OrderType } from "../utils/order-splitter";
 import type { AppliedOrderDiscount, OrderSourceContext } from "../schemas/firestore";
@@ -183,6 +184,20 @@ export interface Order {
      * read it from site settings, because `gst` is in `PRIVATE_SITE_FIELDS`
      * after an earlier deny-list projection shipped it publicly (Root Cause #70).
      */
+    /**
+     * ── EMI, buyer-facing ─────────────────────────────────────────────────
+     *
+     * 🛑 Declared here because `EmiInstallmentsPanel` is useless without it,
+     * and the absence was Root Cause #57's exact shape: the whole EMI schedule
+     * sat on `OrderDocument` and `orderDocumentToOrder` mapped none of it, so
+     * every buyer surface would have rendered its "no EMI plan" fallback with
+     * a real plan on the record. That reads as "this order isn't on EMI"
+     * rather than as a bug, which is why it survives.
+     */
+    emiEnabled?: boolean;
+    emiInstallments?: EmiInstallment[];
+    /** Sum of unpaid instalments. 0 once the plan is settled. */
+    emiRemainingBalance?: number;
     supplierGstin?: string;
     supplierLegalName?: string;
     supplierAddress?: string;

package/dist/features/parts/components/PartDetailPageView.js

@@ -1,6 +1,8 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { Section, Container, Stack, Row, Div, Heading, Text, Span, TextLink, Badge, } from "../../../ui/index.js";
+import { Section, Container, Stack, Row, Div, Heading, Text, Span, TextLink, Badge, Anchor, } from "../../../ui/index.js";
 import { SpecTable } from "../../../ui/components/SpecTable.js";
+import { RecordOwnerQuickActions } from "../../admin/components/RecordOwnerQuickActions.js";
+import { ROUTES } from "../../../next/routing/route-map.js";
 import { PART_SLOT_LABEL, } from "../schemas/firestore.js";
 /**
  * The buyer-facing label for each WBO tournament format, in the order a
@@ -100,12 +102,12 @@ export function PartDetailPageView({ part, usedBy, listings, listingsTruncated,
         : [];
     /* Only the formats this part is actually ruled on — see the note below. */
     const legalFormats = Object.entries(part.wboLegality ?? {}).filter(([, v]) => typeof v === "boolean");
-    return (_jsx(Section, { padding: "y-lg", children: _jsx(Container, { size: "lg", children: _jsxs(Stack, { gap: "lg", className: "min-w-0", children: [_jsxs(Stack, { gap: "xs", className: "min-w-0", children: [_jsx(Text, { size: "sm", color: "muted", children: _jsx(TextLink, { href: hrefForClassification(part.slot), children: classification }) }), _jsx(Heading, { level: 1, children: part.name }), _jsxs(Row, { gap: "xs", wrap: true, align: "center", className: "min-w-0", children: [part.code && _jsx(Badge, { variant: "info", children: part.code }), typeof part.weightG === "number" && (_jsxs(Badge, { variant: "default", children: [part.weightG, " g"] }))] }), aliases.length > 0 && (_jsxs(Text, { size: "sm", color: "muted", children: ["Also written: ", aliases.join(" · ")] }))] }), specRows.length > 1 && (_jsxs(Stack, { gap: "sm", className: "min-w-0", children: [_jsx(Heading, { level: 2, size: "lg", children: "Specifications" }), _jsx(SpecTable, { rows: specRows })] })), ratingRows.length > 0 && (_jsxs(Stack, { gap: "sm", className: "min-w-0", children: [_jsx(Heading, { level: 2, size: "lg", children: "Ratings" }), _jsx(SpecTable, { rows: ratingRows.map((r) => ({
+    return (_jsx(Section, { padding: "y-lg", children: _jsx(Container, { size: "lg", children: _jsxs(Stack, { gap: "lg", className: "min-w-0", children: [_jsxs(Stack, { gap: "xs", className: "min-w-0", children: [_jsx(Text, { size: "sm", color: "muted", children: _jsx(TextLink, { href: hrefForClassification(part.slot), children: classification }) }), _jsx(Heading, { level: 1, children: part.name }), _jsx(RecordOwnerQuickActions, { resource: "PART", recordId: part.id, placement: "detail", recordLabel: part.name }), _jsxs(Row, { gap: "xs", wrap: true, align: "center", className: "min-w-0", children: [part.code && _jsx(Badge, { variant: "info", children: part.code }), typeof part.weightG === "number" && (_jsxs(Badge, { variant: "default", children: [part.weightG, " g"] }))] }), aliases.length > 0 && (_jsxs(Text, { size: "sm", color: "muted", children: ["Also written: ", aliases.join(" · ")] }))] }), specRows.length > 1 && (_jsxs(Stack, { gap: "sm", className: "min-w-0", children: [_jsx(Heading, { level: 2, size: "lg", children: "Specifications" }), _jsx(SpecTable, { rows: specRows })] })), ratingRows.length > 0 && (_jsxs(Stack, { gap: "sm", className: "min-w-0", children: [_jsx(Heading, { level: 2, size: "lg", children: "Ratings" }), _jsx(SpecTable, { rows: ratingRows.map((r) => ({
                                     name: r.label,
                                     value: `${r.value} / 100`,
                                 })) }), _jsxs(Text, { size: "xs", color: "faint", children: ["Rescaled to 0\u2013100 for comparison across generations", typeof part.ratingScale === "number"
                                         ? `; rated 0–${part.ratingScale} at source`
-                                        : "", "."] })] })), legalFormats.length > 0 && (_jsxs(Stack, { gap: "sm", className: "min-w-0", children: [_jsx(Heading, { level: 2, size: "lg", children: "Tournament legality" }), _jsx(Row, { gap: "xs", wrap: true, align: "center", className: "min-w-0", children: legalFormats.map(([format, allowed]) => (_jsxs(Badge, { variant: allowed ? "success" : "danger", children: [WBO_FORMAT_LABEL[format] ?? format, allowed ? " ✓" : " ✗"] }, format))) }), _jsx(Text, { size: "xs", color: "faint", children: "World Beyblade Organization formats this part is ruled on. A format not listed has no ruling for it." })] })), _jsxs(Stack, { gap: "sm", className: "min-w-0", children: [_jsx(Heading, { level: 2, size: "lg", children: usedBy.length > 0
+                                        : "", "."] })] })), legalFormats.length > 0 && (_jsxs(Stack, { gap: "sm", className: "min-w-0", children: [_jsx(Heading, { level: 2, size: "lg", children: "Tournament legality" }), _jsx(Row, { gap: "xs", wrap: true, align: "center", className: "min-w-0", children: legalFormats.map(([format, allowed]) => (_jsxs(Badge, { variant: allowed ? "success" : "danger", children: [WBO_FORMAT_LABEL[format] ?? format, allowed ? " ✓" : " ✗"] }, format))) }), _jsx(Text, { size: "xs", color: "faint", children: "World Beyblade Organization formats this part is ruled on. A format not listed has no ruling for it." })] })), part.sourceUrl && (_jsx(Div, { children: _jsxs(Text, { size: "xs", color: "faint", children: ["Facts on this page are drawn from a community wiki under CC\u00A0BY-SA.", " ", _jsx(Anchor, { href: part.sourceUrl, tone: "muted", underline: "always", children: "Source" }), " · ", _jsx(TextLink, { href: String(ROUTES.PUBLIC.CREDITS), children: "Credits" })] }) })), _jsxs(Stack, { gap: "sm", className: "min-w-0", children: [_jsx(Heading, { level: 2, size: "lg", children: usedBy.length > 0
                                     ? `Used by ${usedBy.length} ${usedBy.length === 1 ? "model" : "models"}`
                                     : "Used by" }), usedBy.length === 0 ? (_jsx(Text, { color: "muted", size: "sm", children: "No model in our database records this part yet." })) : (_jsx(Stack, { gap: "xs", className: "min-w-0", children: usedBy.map((m) => (_jsxs(Row, { gap: "sm", align: "center", padding: "inline", surface: "card", rounded: "md", border: "subtle", className: "min-w-0", children: [_jsxs(Div, { className: "flex-1 min-w-0", children: [m.categoryId ? (_jsx(TextLink, { href: hrefForModel(m.categoryId), children: m.name })) : (
                                                 /* 49 of 259 compositions did not join to a category.

package/dist/features/parts/components/PartsSearchBox.js

@@ -35,13 +35,88 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import React from "react";
 import { Div, Input, Stack, Text, TextLink } from "../../../ui/index.js";
 import { useSiteSearch } from "../../search/hooks/useSiteSearch.js";
+import { useUrlTable } from "../../../react/hooks/useUrlTable.js";
+import { TABLE_KEYS } from "../../../constants/table-keys.js";
 /** Only this slice of the index. See `resolveEntity`'s `types` parameter. */
 const PART_TYPES = ["part"];
 /** Stable identity — a `useMemo` dependency inside the hook. */
 const partLabel = () => "Parts";
 export function PartsSearchBox({ indexEnabled, placeholder = "Search parts by name or code — RF, 105, Rubber Flat…", limit = 10, }) {
-    const [query, setQuery] = React.useState("");
-    const [active, setActive] = React.useState(false);
+    /*
+     * ── 🛑 THE QUERY LIVES IN THE URL, SO A SEARCH IS SHAREABLE ──────────────
+     *
+     * This was `React.useState("")`, which meant typing filtered the list and
+     * left the address bar on `/parts`. Every detail page here is a real slug
+     * (`/parts/{classification}/{code}`, `/beys/{slug}`) and every other listing
+     * surface puts its state in the URL — `/search?q=…` reads `searchParams`
+     * server-side, and the category pages go as far as path segments
+     * (`/categories/{slug}/{tab}/sort/{sortKey}/page/{page}`). A client-local
+     * box was the one surface where you could not send someone what you were
+     * looking at.
+     *
+     * `useUrlTable` is the mechanism, not a second one invented here: it owns
+     * `router.replace()`, uses replace rather than push so typing does not fill
+     * the back button, and `TABLE_KEYS.QUERY` is the same `q` the rest of the
+     * app reads.
+     *
+     * 🛑 TWO pieces of state, deliberately, and they are not redundant. `draft`
+     * drives the input so a keystroke is never waiting on a navigation; the URL
+     * is the shareable record, written on a debounce. Driving the input straight
+     * from `searchParams` makes every character a round trip through the router
+     * and the field feels broken on a slow render.
+     *
+     * 🛑 `useSearchParams` requires a `<Suspense>` ancestor or the build fails
+     * on prerender (Root Cause #17b). The root locale layout has one, which is
+     * what the ~246 comments citing that pattern are about.
+     */
+    /*
+     * 🛑 DESTRUCTURED, because `useUrlTable` returns a fresh object literal every
+     * render while the callbacks inside it are `useCallback`-memoised. Depending
+     * on `table` would make the effect below re-run on every render; depending on
+     * `set`/`clear` is stable. Same trap as the `loadOptions` identity bug in
+     * `PaginatedSelect`, where an unstable function re-triggered a fetch effect.
+     */
+    const { get, set, clear } = useUrlTable();
+    const urlQuery = get(TABLE_KEYS.QUERY) ?? "";
+    const [draft, setDraft] = React.useState(urlQuery);
+    /*
+     * 🛑 SEEDED FROM THE URL, not `false`.
+     *
+     * `useSiteSearch` only fetches the index when `active`, which previously
+     * meant "the user has focused the box". Arriving on `/parts?q=rubber-flat`
+     * from a shared link, `active` would be false — so the query would sit in
+     * the field and in the address bar having searched NOTHING until the visitor
+     * clicked into the input. That defeats the entire reason for putting the
+     * query in the URL, and it is the kind of gap that looks like the link
+     * "didn't work" rather than like a missing fetch.
+     */
+    const [active, setActive] = React.useState(urlQuery.length > 0);
+    /*
+     * Back/forward and a shared link both change the URL without touching the
+     * input, so the draft follows the URL when the URL moves on its own.
+     * Guarded on inequality — without that this fights the user's typing.
+     */
+    React.useEffect(() => {
+        setDraft((prev) => (prev === urlQuery ? prev : urlQuery));
+    }, [urlQuery]);
+    /*
+     * 🛑 Debounced, because `router.replace` on every keystroke is a navigation
+     * per character. 300ms is the same order the rest of the app uses for a
+     * search field, and the cleanup makes the last keystroke the one that wins.
+     */
+    React.useEffect(() => {
+        if (draft === urlQuery)
+            return;
+        const t = setTimeout(() => {
+            if (draft)
+                set(TABLE_KEYS.QUERY, draft);
+            else
+                clear([TABLE_KEYS.QUERY]);
+        }, 300);
+        return () => clearTimeout(t);
+    }, [draft, urlQuery, set, clear]);
+    /* The index is searched on the URL's value — the thing that is shareable. */
+    const query = urlQuery;
     const { status, result } = useSiteSearch(query, {
         active,
         indexEnabled,
@@ -50,8 +125,8 @@ export function PartsSearchBox({ indexEnabled, placeholder = "Search parts by na
     });
     const hits = result?.groups[0]?.hits ?? [];
     const typed = query.trim().length > 0;
-    return (_jsxs(Stack, { gap: "sm", className: "min-w-0", children: [_jsx(Input, { type: "search", value: query, placeholder: placeholder, "aria-label": "Search parts", onFocus: () => setActive(true), onChange: (event) => {
+    return (_jsxs(Stack, { gap: "sm", className: "min-w-0", children: [_jsx(Input, { type: "search", value: draft, placeholder: placeholder, "aria-label": "Search parts", onFocus: () => setActive(true), onChange: (event) => {
                     setActive(true);
-                    setQuery(event.target.value);
+                    setDraft(event.target.value);
                 } }), typed && status === "loading" && _jsx(Text, { color: "muted", children: "Searching\u2026" }), typed && (status === "failed" || status === "disabled") && (_jsx(Text, { size: "sm", color: "muted", children: "Part search is unavailable right now \u2014 browse by classification below." })), typed && status === "ready" && hits.length === 0 && (_jsx(Text, { color: "muted", children: "No part matches that name or code." })), hits.length > 0 && (_jsx(Stack, { gap: "xs", className: "min-w-0", children: hits.slice(0, limit).map((hit) => (_jsxs(Div, { surface: "card", padding: "sm", rounded: "md", border: "subtle", children: [_jsx(TextLink, { href: hit.href, children: hit.title }), hit.detail && (_jsx(Text, { size: "xs", color: "muted", children: hit.detail }))] }, hit.id))) }))] }));
 }

package/dist/features/parts/schemas/admin-edit.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Field-level protection for hand-corrections to GENERATED reference data.
+ *
+ * ── 🛑 THE PROBLEM THIS SOLVES ────────────────────────────────────────────
+ *
+ * `partGlossary` (2,488 rows) and `beys` (1,988) are produced by committed
+ * generators from a crawled corpus, and `appkit-seed load` writes them with
+ * `set(doc, { merge: true })`. A merge-write overwrites every key present in
+ * the payload — so an admin who corrects a wrong extracted weight loses that
+ * correction on the next reseed, silently, and the row goes back to being
+ * wrong while `appkit-seed status` reports the collection perfectly in sync
+ * (it counts ids, and the id did not change).
+ *
+ * That is not hypothetical for this dataset. This session alone found five
+ * wrong claims in the source corpus — an inverted tip transition, a mode that
+ * was actually launch spin direction, a mechanism on the wrong part, a part
+ * with no modes at all, and a part named "Duo:Dual" that is Delta Drive. A
+ * hand-correction is the fast path for exactly those, and it has to survive.
+ *
+ * ── 🛑 FIELD-LEVEL, NOT ROW-LEVEL ────────────────────────────────────────
+ *
+ * The obvious shape is one boolean meaning "do not touch this row". It is
+ * wrong: freezing a whole row because somebody fixed one weight means the row
+ * stops receiving every genuine improvement the generator makes afterwards —
+ * a better description, a newly resolved part id, a corrected release date.
+ * The row quietly falls out of the dataset's own maintenance.
+ *
+ * So `adminEditedFields` names the keys a human owns. The loader strips
+ * exactly those from its payload and writes everything else, which means a
+ * corrected weight and an improved description can both be true at once.
+ *
+ * `adminEdited` is a plain boolean beside it purely so the loader can find
+ * these rows with ONE equality query per collection instead of reading all
+ * 4,476 documents to discover the handful that matter. `array-contains` on
+ * `adminEditedFields` cannot answer "has any value", and an `orderBy` or `!=`
+ * on it would silently exclude every row that lacks the field — which is all
+ * of them (Root Cause #100).
+ *
+ * 🛑 KEEP THE TWO IN SYNC. `adminEdited` is `adminEditedFields.length > 0`.
+ * Writing one without the other either hides a protected row from the loader
+ * (so the edit is lost anyway) or makes the loader fetch a row with nothing to
+ * protect. `applyAdminEdit` is the only function that should set either.
+ */
+/** The fields a human has taken ownership of on one generated row. */
+export interface AdminEditableRecord {
+    /**
+     * `true` iff `adminEditedFields` is non-empty. Exists ONLY so the seed
+     * loader can find protected rows with one indexed equality.
+     */
+    adminEdited?: boolean;
+    /**
+     * Keys the generator must not overwrite. Dot paths are NOT supported — a
+     * nested object is owned whole, because a merge-write replaces a map wholesale
+     * and protecting one leaf of it is not something `{ merge: true }` can express.
+     */
+    adminEditedFields?: string[];
+    /** When the most recent hand-edit landed. Audit trail, never read by logic. */
+    adminEditedAt?: Date;
+    /** Who. The Auth UID, never a name — this travels into no public projection. */
+    adminEditedBy?: string;
+}
+/**
+ * Merge a hand-edit into a record, keeping the two protection fields honest.
+ *
+ * Returns the patch to write — the caller's changed fields plus the updated
+ * ownership set. 🛑 Ownership is CUMULATIVE: editing the weight today and the
+ * description tomorrow must leave both protected, so the existing set is
+ * unioned rather than replaced.
+ */
+export declare function applyAdminEdit<TChanges extends object>(existing: Pick<AdminEditableRecord, "adminEditedFields"> | null | undefined, changes: TChanges, actorUid: string): TChanges & Required<Pick<AdminEditableRecord, "adminEdited" | "adminEditedFields">> & {
+    adminEditedAt: Date;
+    adminEditedBy: string;
+};
+/**
+ * Strip the fields a human owns out of a generator payload.
+ *
+ * Used by `appkit/scripts/seed-cli.mjs`. Exported from here rather than
+ * duplicated there so the rule has one definition — the CLI is `.mjs` and
+ * reads this through the built package, the same way it reads the seed data.
+ */
+export declare function stripAdminOwnedFields<T extends object>(payload: T, ownedFields: readonly string[] | undefined): Partial<T>;

package/dist/features/parts/schemas/admin-edit.js

@@ -0,0 +1,89 @@
+/**
+ * Field-level protection for hand-corrections to GENERATED reference data.
+ *
+ * ── 🛑 THE PROBLEM THIS SOLVES ────────────────────────────────────────────
+ *
+ * `partGlossary` (2,488 rows) and `beys` (1,988) are produced by committed
+ * generators from a crawled corpus, and `appkit-seed load` writes them with
+ * `set(doc, { merge: true })`. A merge-write overwrites every key present in
+ * the payload — so an admin who corrects a wrong extracted weight loses that
+ * correction on the next reseed, silently, and the row goes back to being
+ * wrong while `appkit-seed status` reports the collection perfectly in sync
+ * (it counts ids, and the id did not change).
+ *
+ * That is not hypothetical for this dataset. This session alone found five
+ * wrong claims in the source corpus — an inverted tip transition, a mode that
+ * was actually launch spin direction, a mechanism on the wrong part, a part
+ * with no modes at all, and a part named "Duo:Dual" that is Delta Drive. A
+ * hand-correction is the fast path for exactly those, and it has to survive.
+ *
+ * ── 🛑 FIELD-LEVEL, NOT ROW-LEVEL ────────────────────────────────────────
+ *
+ * The obvious shape is one boolean meaning "do not touch this row". It is
+ * wrong: freezing a whole row because somebody fixed one weight means the row
+ * stops receiving every genuine improvement the generator makes afterwards —
+ * a better description, a newly resolved part id, a corrected release date.
+ * The row quietly falls out of the dataset's own maintenance.
+ *
+ * So `adminEditedFields` names the keys a human owns. The loader strips
+ * exactly those from its payload and writes everything else, which means a
+ * corrected weight and an improved description can both be true at once.
+ *
+ * `adminEdited` is a plain boolean beside it purely so the loader can find
+ * these rows with ONE equality query per collection instead of reading all
+ * 4,476 documents to discover the handful that matter. `array-contains` on
+ * `adminEditedFields` cannot answer "has any value", and an `orderBy` or `!=`
+ * on it would silently exclude every row that lacks the field — which is all
+ * of them (Root Cause #100).
+ *
+ * 🛑 KEEP THE TWO IN SYNC. `adminEdited` is `adminEditedFields.length > 0`.
+ * Writing one without the other either hides a protected row from the loader
+ * (so the edit is lost anyway) or makes the loader fetch a row with nothing to
+ * protect. `applyAdminEdit` is the only function that should set either.
+ */
+/**
+ * Merge a hand-edit into a record, keeping the two protection fields honest.
+ *
+ * Returns the patch to write — the caller's changed fields plus the updated
+ * ownership set. 🛑 Ownership is CUMULATIVE: editing the weight today and the
+ * description tomorrow must leave both protected, so the existing set is
+ * unioned rather than replaced.
+ */
+export function applyAdminEdit(existing, changes, actorUid) {
+    const owned = new Set(existing?.adminEditedFields ?? []);
+    for (const key of Object.keys(changes)) {
+        /*
+         * The protection fields themselves are never protected — that would make
+         * the set unmodifiable by the next edit.
+         */
+        if (key.startsWith("adminEdited"))
+            continue;
+        owned.add(key);
+    }
+    const fields = [...owned].sort();
+    return {
+        ...changes,
+        adminEditedFields: fields,
+        adminEdited: fields.length > 0,
+        adminEditedAt: new Date(),
+        adminEditedBy: actorUid,
+    };
+}
+/**
+ * Strip the fields a human owns out of a generator payload.
+ *
+ * Used by `appkit/scripts/seed-cli.mjs`. Exported from here rather than
+ * duplicated there so the rule has one definition — the CLI is `.mjs` and
+ * reads this through the built package, the same way it reads the seed data.
+ */
+export function stripAdminOwnedFields(payload, ownedFields) {
+    if (!ownedFields?.length)
+        return payload;
+    const out = {};
+    for (const [k, v] of Object.entries(payload)) {
+        if (ownedFields.includes(k))
+            continue;
+        out[k] = v;
+    }
+    return out;
+}