@mohasinac/appkit 4.53.2 → 4.54.0-next.0

package/dist/features/layout/useIsDesktop.js

@@ -0,0 +1,48 @@
+"use client";
+import { useEffect, useState } from "react";
+/**
+ * The line at which the layout stops being a phone.
+ *
+ * 64rem is Tailwind's `lg` — deliberately the same breakpoint `BottomNavbar`
+ * disappears at, so every decision that depends on "is there a tab bar at the
+ * bottom of this screen" flips at one place.
+ */
+export const DESKTOP_QUERY = "(min-width: 64rem)";
+/**
+ * `true` at `lg` and up.
+ *
+ * ── 🛑 WHY A HOOK AND NOT A `lg:` CLASS ────────────────────────────────────
+ *
+ * Three callers need the breakpoint as a VALUE, not as styling:
+ *
+ *   - `BottomChrome` must know which CSS variable to publish — a media query
+ *     can move the box but cannot tell a `ResizeObserver` which end of the
+ *     screen it landed at.
+ *   - `SideActionDock` and `BottomActions` are the two halves of one control
+ *     and must never both be mounted: two toolbars reading the same context,
+ *     both `fixed`, both dispatching the same callbacks. Hiding one with
+ *     `display:none` would still mount it, still run its observers, and still
+ *     let a stray `:focus` land inside an invisible bar.
+ *
+ * And the class form is actively unsafe here. Both Tailwind configs set
+ * `important: true`, so a `lg:` override and its unprefixed base tie on
+ * specificity AND on `!important` — a media query adds no specificity — and
+ * the winner is decided by EMISSION ORDER in the built CSS, which is invisible
+ * from the call site. That is exactly how `BottomChrome` ended up anchored to
+ * both edges at once and published an 801px phantom bar (see its header).
+ *
+ * SSR renders the mobile branch, because that is the branch that is correct
+ * when nothing is known: a phone that briefly gets the dock has lost its only
+ * CTA, while a desktop that briefly gets the bar has a bar.
+ */
+export function useIsDesktop() {
+    const [isDesktop, setIsDesktop] = useState(false);
+    useEffect(() => {
+        const mq = window.matchMedia(DESKTOP_QUERY);
+        const sync = () => setIsDesktop(mq.matches);
+        sync();
+        mq.addEventListener("change", sync);
+        return () => mq.removeEventListener("change", sync);
+    }, []);
+    return isDesktop;
+}

package/dist/features/media/messages/en.json

@@ -1,67 +1,67 @@
-{
-  "mediaEditor": {
-    "cropTitle": "Crop Image",
-    "cropInstruction": "Drag to reposition. Use the zoom slider or +/- keys to zoom.",
-    "cropPreviewAlt": "Preview",
-    "cropZoom": "Zoom",
-    "cropZoomIn": "Zoom in",
-    "cropZoomOut": "Zoom out",
-    "cropRotateLeft": "Rotate left 90°",
-    "cropRotateRight": "Rotate right 90°",
-    "cropFlipH": "Flip horizontally",
-    "cropFlipV": "Flip vertically",
-    "cropWarningTitle": "Low zoom",
-    "cropWarningMessage": "Zoom in for better quality.",
-    "cropPosition": "Position",
-    "cropReset": "Reset",
-    "cropSave": "Save Crop",
-    "cropCancel": "Cancel",
-    "trimTitle": "Trim Video",
-    "trimInstruction": "Set the start and end times, then click Trim.",
-    "trimStart": "Start",
-    "trimEnd": "End",
-    "trimDuration": "Duration: {duration}s",
-    "trimQuality": "Quality",
-    "trimQualityLow": "Low",
-    "trimQualityMedium": "Medium",
-    "trimQualityHigh": "High",
-    "trimSave": "Trim Video",
-    "trimSkip": "Skip",
-    "trimming": "Trimming…",
-    "thumbnailTitle": "Select Thumbnail",
-    "thumbnailInstruction": "Seek to the frame you want to use as the thumbnail.",
-    "thumbnailCapture": "Use This Frame",
-    "thumbnailSkip": "Skip",
-    "thumbnailCapturing": "Capturing…",
-    "thumbnailUploading": "Uploading…",
-    "cropSuccess": "Image cropped",
-    "trimSuccess": "Video trimmed",
-    "thumbnailSuccess": "Thumbnail saved",
-    "cropError": "Failed to crop image",
-    "trimError": "Failed to trim video",
-    "thumbnailError": "Failed to capture thumbnail",
-    "editImage": "Edit / Crop",
-    "editVideo": "Trim / Thumbnail"
-  },
-  "camera": {
-    "takePhoto": "Take Photo",
-    "startRecording": "Start Recording",
-    "stopRecording": "Stop Recording",
-    "flipCamera": "Flip Camera",
-    "switchToCamera": "Use Camera",
-    "switchToUpload": "Upload File",
-    "cameraError": "Camera unavailable",
-    "permissionDenied": "Camera permission denied. Please allow access in your browser settings.",
-    "notSupported": "Camera is not supported on this device",
-    "starting": "Starting camera..."
-  },
-  "upload": {
-    "change": "Change",
-    "remove": "Remove",
-    "clickToUpload": "Click to upload",
-    "uploading": "Uploading…",
-    "uploadingProgress": "Uploading {progress}%…",
-    "replaceFile": "Replace file",
-    "chooseFile": "Choose file to upload"
-  }
-}
+{
+  "mediaEditor": {
+    "cropTitle": "Crop Image",
+    "cropInstruction": "Drag to reposition. Use the zoom slider or +/- keys to zoom.",
+    "cropPreviewAlt": "Preview",
+    "cropZoom": "Zoom",
+    "cropZoomIn": "Zoom in",
+    "cropZoomOut": "Zoom out",
+    "cropRotateLeft": "Rotate left 90°",
+    "cropRotateRight": "Rotate right 90°",
+    "cropFlipH": "Flip horizontally",
+    "cropFlipV": "Flip vertically",
+    "cropWarningTitle": "Low zoom",
+    "cropWarningMessage": "Zoom in for better quality.",
+    "cropPosition": "Position",
+    "cropReset": "Reset",
+    "cropSave": "Save Crop",
+    "cropCancel": "Cancel",
+    "trimTitle": "Trim Video",
+    "trimInstruction": "Set the start and end times, then click Trim.",
+    "trimStart": "Start",
+    "trimEnd": "End",
+    "trimDuration": "Duration: {duration}s",
+    "trimQuality": "Quality",
+    "trimQualityLow": "Low",
+    "trimQualityMedium": "Medium",
+    "trimQualityHigh": "High",
+    "trimSave": "Trim Video",
+    "trimSkip": "Skip",
+    "trimming": "Trimming…",
+    "thumbnailTitle": "Select Thumbnail",
+    "thumbnailInstruction": "Seek to the frame you want to use as the thumbnail.",
+    "thumbnailCapture": "Use This Frame",
+    "thumbnailSkip": "Skip",
+    "thumbnailCapturing": "Capturing…",
+    "thumbnailUploading": "Uploading…",
+    "cropSuccess": "Image cropped",
+    "trimSuccess": "Video trimmed",
+    "thumbnailSuccess": "Thumbnail saved",
+    "cropError": "Failed to crop image",
+    "trimError": "Failed to trim video",
+    "thumbnailError": "Failed to capture thumbnail",
+    "editImage": "Edit / Crop",
+    "editVideo": "Trim / Thumbnail"
+  },
+  "camera": {
+    "takePhoto": "Take Photo",
+    "startRecording": "Start Recording",
+    "stopRecording": "Stop Recording",
+    "flipCamera": "Flip Camera",
+    "switchToCamera": "Use Camera",
+    "switchToUpload": "Upload File",
+    "cameraError": "Camera unavailable",
+    "permissionDenied": "Camera permission denied. Please allow access in your browser settings.",
+    "notSupported": "Camera is not supported on this device",
+    "starting": "Starting camera..."
+  },
+  "upload": {
+    "change": "Change",
+    "remove": "Remove",
+    "clickToUpload": "Click to upload",
+    "uploading": "Uploading…",
+    "uploadingProgress": "Uploading {progress}%…",
+    "replaceFile": "Replace file",
+    "chooseFile": "Choose file to upload"
+  }
+}

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

@@ -0,0 +1,24 @@
+export interface PurchaseContext {
+    order: {
+        id: string;
+        shortRef: string;
+        status: string;
+        orderDate: string | null;
+        trackHref: string;
+        detailHref: string;
+    } | null;
+    review: {
+        id: string;
+        rating: number;
+        status: string;
+    } | null;
+    windowDays: number;
+}
+export interface YourPurchaseStripProps {
+    productId: string;
+    /** Opens the review editor. Omit to render the review half as a link only. */
+    onEditReview?: (reviewId: string) => void;
+    onWriteReview?: () => void;
+    className?: string;
+}
+export declare function YourPurchaseStrip({ productId, onEditReview, onWriteReview, className, }: YourPurchaseStripProps): import("react").JSX.Element | null;

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

@@ -0,0 +1,77 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * "You ordered this — track it" and "your review — edit it", on a product page.
+ *
+ * ── Why this exists ───────────────────────────────────────────────────────
+ *
+ * A buyer looking at an item they already own had no link to their own order
+ * and no link to their own review. Both records exist; nothing connected them
+ * to the product page, so the route was: remember you bought it, go to
+ * /user/orders, page through, find it.
+ *
+ * ── Three rules this component is built around ────────────────────────────
+ *
+ * 🛑 NO MONEY. An order total here would need the guest-price gate, and the
+ * strip is signed-in-only by construction — omitting the amount removes the
+ * question entirely rather than answering it carefully.
+ *
+ * 🛑 SAY THE WINDOW. The lookup is bounded to 90 days (see the route: order
+ * `items[]` holds objects, so there is no index for "order containing this
+ * product"). When nothing is found the copy is "No order in the last 90 days",
+ * never "you haven't bought this". A filtered empty result reported as an
+ * absolute zero is a lie the buyer cannot check — the same defect
+ * `UserOrdersView` carries a long comment about.
+ *
+ * 🛑 RENDER NOTHING UNTIL RESOLVED. Public product pages are ISR and read no
+ * session, so `loading` starts true on every hard load even for signed-in
+ * users. Showing the signed-out state first would flash "no order" at someone
+ * who has one.
+ *
+ * @tag domain:orders
+ * @tag layer:components
+ * @tag access:client
+ */
+import { useApiQuery } from "../../../client/api/useApiQuery.js";
+import { apiClient } from "../../../http/index.js";
+import { useOptionalSession } from "../../../react/contexts/SessionContext.js";
+import { ACTIONS } from "../../../_internal/shared/actions/action-registry.js";
+import { ACCOUNT_ENDPOINTS } from "../../../constants/api-endpoints.js";
+import { ROUTES } from "../../../next/routing/route-map.js";
+import { Button, Div, Row, Span, Stack, Text, TextLink } from "../../../ui/index.js";
+import { Icon } from "../../../ui/components/Icon.js";
+import { formatDate } from "../../../utils/index.js";
+export function YourPurchaseStrip({ productId, onEditReview, onWriteReview, className = "", }) {
+    const session = useOptionalSession();
+    const signedIn = Boolean(session?.user?.uid);
+    const query = useApiQuery({
+        queryKey: ["user", "purchases", productId],
+        queryFn: async () => {
+            const res = await apiClient.get(ACCOUNT_ENDPOINTS.PURCHASE_CONTEXT(productId));
+            return (res?.data ?? { order: null, review: null, windowDays: 90 });
+        },
+        // Only ask once we know there is somebody to ask about.
+        enabled: signedIn,
+        staleTime: 60000,
+        silentBackgroundFailures: true,
+    });
+    /*
+     * A guest, or auth not yet resolved, renders nothing at all. There is no
+     * useful signed-out state here: "sign in to see your order" is noise on a
+     * page whose primary job is selling the item.
+     */
+    if (!session || session.loading || !signedIn)
+        return null;
+    if (query.isLoading || !query.data)
+        return null;
+    const { order, review, windowDays } = query.data;
+    // Nothing bought and nothing written — stay out of the way entirely.
+    if (!order && !review)
+        return null;
+    return (_jsx(Div, { surface: "muted", rounded: "xl", padding: "md", border: "subtle", className: className, children: _jsxs(Stack, { gap: "sm", children: [order ? (_jsxs(Row, { align: "center", justify: "between", gap: "sm", wrap: true, children: [_jsxs(Row, { align: "center", gap: "sm", children: [_jsx(Icon, { name: "order", size: "sm", tone: "muted" }), _jsxs(Text, { size: "sm", children: ["You ordered this", order.orderDate ? ` on ${formatDate(order.orderDate)}` : "", " \u00B7", " ", _jsxs(Span, { className: "font-mono", children: ["#", order.shortRef] })] })] }), _jsxs(Row, { align: "center", gap: "sm", children: [_jsx(Button, { asChild: true, variant: "outline", size: "sm", children: _jsx(TextLink, { href: order.trackHref, children: ACTIONS.USER["track-order"].label }) }), _jsx(Button, { asChild: true, variant: "ghost", size: "sm", children: _jsx(TextLink, { href: order.detailHref, children: ACTIONS.USER["view-order"].label }) })] })] })) : (
+                /*
+                 * 🛑 Bounded, and it says so. Not "you haven't bought this".
+                 */
+                _jsxs(Text, { size: "sm", color: "muted", children: ["No order for this item in the last ", windowDays, " days.", " ", _jsx(TextLink, { href: String(ROUTES.USER.ORDERS), children: "See all your orders" })] })), review ? (_jsxs(Row, { align: "center", justify: "between", gap: "sm", wrap: true, children: [_jsxs(Row, { align: "center", gap: "sm", children: [_jsx(Icon, { name: "review", size: "sm", tone: "muted", filled: true }), _jsxs(Text, { size: "sm", children: ["Your review: ", review.rating, "/5", review.status !== "approved" ? ` · ${review.status}` : ""] })] }), onEditReview && (_jsx(Button, { variant: "outline", size: "sm", onClick: () => onEditReview(review.id), children: ACTIONS.REVIEW.edit.label }))] })) : (order &&
+                    onWriteReview && (_jsxs(Row, { align: "center", justify: "between", gap: "sm", wrap: true, children: [_jsx(Text, { size: "sm", color: "muted", children: "You have not reviewed this yet." }), _jsx(Button, { variant: "outline", size: "sm", onClick: onWriteReview, children: ACTIONS.REVIEW.write.label })] })))] }) }));
+}

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

@@ -1,6 +1,5 @@
 export { OrderCard, OrdersList } from "./OrdersList";
 export { OrderAddonBadges, type OrderAddonBadgesOrder, type OrderAddonBadgesProps, } from "./OrderAddonBadges";
-export { MarketplaceOrderCard, type MarketplaceOrderCardLabels, type MarketplaceOrderCardLinks, type MarketplaceOrderCardOrder, type MarketplaceOrderCardProps, } from "./MarketplaceOrderCard";
 export { OrderFilters, ORDER_FILTER_KEYS, ORDER_ADMIN_SORT_OPTIONS, ORDER_SELLER_SORT_OPTIONS, ORDER_USER_SORT_OPTIONS, getOrderFilterKeys, getOrderSortOptions, } from "./OrderFilters";
 export type { OrderFiltersProps, OrderFilterVariant } from "./OrderFilters";
 export { OrderSiblingPayments } from "./OrderSiblingPayments";
@@ -13,3 +12,5 @@ export { RefundHistoryTable } from "./RefundHistoryTable";
 export type { RefundHistoryTableProps } from "./RefundHistoryTable";
 export { RefundRequestView } from "./RefundRequestView";
 export type { RefundRequestViewProps } from "./RefundRequestView";
+export { YourPurchaseStrip } from "./YourPurchaseStrip";
+export type { YourPurchaseStripProps, PurchaseContext } from "./YourPurchaseStrip";

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

@@ -1,9 +1,9 @@
 export { OrderCard, OrdersList } from "./OrdersList.js";
 export { OrderAddonBadges, } from "./OrderAddonBadges.js";
-export { MarketplaceOrderCard, } from "./MarketplaceOrderCard.js";
 export { OrderFilters, ORDER_FILTER_KEYS, ORDER_ADMIN_SORT_OPTIONS, ORDER_SELLER_SORT_OPTIONS, ORDER_USER_SORT_OPTIONS, getOrderFilterKeys, getOrderSortOptions, } from "./OrderFilters.js";
 export { OrderSiblingPayments } from "./OrderSiblingPayments.js";
 export { OrderPaymentSummary } from "./OrderPaymentSummary.js";
 export { OrderStatusTimeline } from "./OrderStatusTimeline.js";
 export { RefundHistoryTable } from "./RefundHistoryTable.js";
 export { RefundRequestView } from "./RefundRequestView.js";
+export { YourPurchaseStrip } from "./YourPurchaseStrip.js";

package/dist/features/orders/utils/order-announcement-message.d.ts

@@ -0,0 +1,18 @@
+export interface PurchaseAnnouncementInput {
+    buyerName: string;
+    firstItemName: string;
+    /** 0 if only one item in the order */
+    additionalItemCount: number;
+    /** Total order amount in decimal rupees */
+    totalAmount: number;
+    orderId: string;
+}
+/**
+ * Plain-text body for the "New order placed" staff notification row.
+ *
+ * Originally built for the WhatsApp purchase announcement. That integration
+ * was removed 2026-10-20, but the builder survives because its output is now
+ * the `adminNotifications` body the admin inbox renders and the daily digest
+ * counts — a durable record rather than a per-admin blast.
+ */
+export declare function buildPurchaseAnnouncementMessage(input: PurchaseAnnouncementInput): string;

package/dist/features/orders/utils/order-announcement-message.js

@@ -0,0 +1,16 @@
+/**
+ * Plain-text body for the "New order placed" staff notification row.
+ *
+ * Originally built for the WhatsApp purchase announcement. That integration
+ * was removed 2026-10-20, but the builder survives because its output is now
+ * the `adminNotifications` body the admin inbox renders and the daily digest
+ * counts — a durable record rather than a per-admin blast.
+ */
+export function buildPurchaseAnnouncementMessage(input) {
+    const { buyerName, firstItemName, additionalItemCount, totalAmount, orderId } = input;
+    const extra = additionalItemCount > 0
+        ? ` + ${additionalItemCount} more item${additionalItemCount > 1 ? "s" : ""}`
+        : "";
+    const amount = totalAmount.toLocaleString("en-IN");
+    return `🛍️ New order! ${buyerName} purchased ${firstItemName}${extra} for ₹${amount}. Order #${orderId}`;
+}

package/dist/features/orders/utils/payment-proof-message.d.ts

@@ -0,0 +1,20 @@
+export interface PaymentProofReviewMessageInput {
+    orderId: string;
+    buyerName: string;
+    productTitle: string;
+    totalAmount: number;
+    reviewUrl: string;
+}
+/**
+ * Tier PP — message body for the buyer/seller "share for review" `wa.me`
+ * link on the order payment page.
+ *
+ * Pure string builder with no crypto and no network, so it is safe to export
+ * from the client-safe barrel. It used to live beside the WhatsApp Cloud API
+ * senders in `features/whatsapp-bot/`, isolated into its own file precisely
+ * because those siblings carried a top-level `import { createHmac } from
+ * "crypto"`. The Cloud API integration was removed 2026-10-20; this builder
+ * survived because it feeds an ordinary `wa.me` deep link, which needs no
+ * token, no registered number and no Meta billing relationship.
+ */
+export declare function buildPaymentProofReviewMessage(input: PaymentProofReviewMessageInput): string;

package/dist/features/orders/utils/payment-proof-message.js

@@ -0,0 +1,17 @@
+/**
+ * Tier PP — message body for the buyer/seller "share for review" `wa.me`
+ * link on the order payment page.
+ *
+ * Pure string builder with no crypto and no network, so it is safe to export
+ * from the client-safe barrel. It used to live beside the WhatsApp Cloud API
+ * senders in `features/whatsapp-bot/`, isolated into its own file precisely
+ * because those siblings carried a top-level `import { createHmac } from
+ * "crypto"`. The Cloud API integration was removed 2026-10-20; this builder
+ * survived because it feeds an ordinary `wa.me` deep link, which needs no
+ * token, no registered number and no Meta billing relationship.
+ */
+export function buildPaymentProofReviewMessage(input) {
+    const { orderId, buyerName, productTitle, totalAmount, reviewUrl } = input;
+    const amount = totalAmount.toLocaleString("en-IN");
+    return `💳 Payment proof submitted! ${buyerName} uploaded proof for "${productTitle}" (₹${amount}). Order #${orderId}. Please review within 2 hours or it auto-confirms: ${reviewUrl}`;
+}

package/dist/features/parts/schemas/firestore.d.ts

@@ -210,6 +210,67 @@ export interface PartColourway {
     /** The bey this colourway was released in. */
     inBey: string;
 }
+/**
+ * The infobox stat grid, as NUMBERS.
+ *
+ * 🛑 This is a deliberate second representation of the `Stats` row in
+ * `specs[]`, not a mirror to keep in sync. The row is a RENDERING — one line,
+ * because six rows of single digits crowd out every real specification on a
+ * part page — and this is the VALUE, which is what a sort, a filter, a
+ * side-by-side comparison and the simulation all need. Neither can do the
+ * other's job, and both are produced by one parse in one pass, so there is no
+ * second write path to forget (unlike Root Cause #42's shape).
+ *
+ * Every key is OPTIONAL because the source states them per part: a page that
+ * gives Attack and Burst and nothing else yields exactly those two. A missing
+ * key is "not stated", never zero — `weight: 0` is a real rating on a
+ * featherweight disc and must stay distinguishable from silence.
+ *
+ * The scale is 0–6 and is the wiki's own editorial judgement, not a
+ * measurement. It is useful for comparison between parts of the same slot and
+ * should not be presented as a physical quantity.
+ */
+export interface PartRatings {
+    attack?: number;
+    defense?: number;
+    stamina?: number;
+    weight?: number;
+    speed?: number;
+    burst?: number;
+    dash?: number;
+    burstResistance?: number;
+    power?: number;
+    height?: number;
+    runTime?: number;
+}
+/**
+ * WBO tournament-format legality.
+ *
+ * 🛑 A format the source does not rule on is ABSENT, never `false`. Three
+ * states exist — legal, banned, and not stated — and collapsing the third into
+ * the second would publish "banned in Burst Classic" as a fact about every
+ * part whose page simply never mentions Burst Classic.
+ */
+export interface PartWboLegality {
+    burst?: boolean;
+    burstGt?: boolean;
+    burstLimited?: boolean;
+    burstClassic?: boolean;
+    xStandard?: boolean;
+    xMasters?: boolean;
+    xOpen?: boolean;
+    mfbStandard?: boolean;
+    mfbLimited?: boolean;
+    mfbZeroG?: boolean;
+    mfb4d?: boolean;
+}
+/**
+ * OUR role vocabulary — 10 values covering all 59 slots.
+ *
+ * Mirrors `PART_ROLE` in `scripts/lib/part-slot-vocab.mjs`, which is the
+ * source. A slot missing from that map yields no `role` rather than a guess.
+ */
+export type PartRole = "chip" | "ring" | "wheel" | "weight" | "base" | "blade" | "track" | "tip" | "gear" | "support";
 export interface PartGlossaryDocument extends BaseDocument {
     /** `${slot}--${codeOrSlug}` — both halves, because a code is not unique. */
     id: string;
@@ -294,6 +355,172 @@ export interface PartGlossaryDocument extends BaseDocument {
      * it is a DIFFERENT axis from colour and must not be folded into it.
      */
     hasMoldVariations?: boolean;
+    /**
+     * The 0–6 stat grid as numbers. Present on 1,149 of 2,490 rows — the source
+     * states it per part, so absence is "not stated", not zero.
+     */
+    ratings?: PartRatings;
+    /**
+     * The ceiling `ratings` are out of — 6, 8 or 100.
+     *
+     * 🛑 LOAD-BEARING, because each generation rates on its own scale and they
+     * share these fields. Measured: Beyblade X rates 0-100 (237 rows) while
+     * Burst rates 0-6 or 0-8 (945 rows), so mean `attack` by slot reads
+     * `blade 31.8` beside `driver 1.78`. Anything that sorts, compares or
+     * simulates on a rating MUST divide by this first; without it a Beyblade X
+     * blade outranks every Burst layer five times over.
+     *
+     * Derived per system from the highest rating observed for it, rounded up to
+     * a standard step — not from a hand-written table, which was wrong within
+     * one run (`warrior-wheel--dragoon` carries attack 7 against a declared 6).
+     */
+    ratingScale?: number;
+    /**
+     * The same axes rescaled to 0-100, so a part can be compared ACROSS
+     * generations — which the game needs, since it has cross-gen battles.
+     *
+     * 🛑 This equalises the EDITORIAL JUDGEMENT, not the capability. A Burst
+     * layer at 6/6 and a Beyblade X blade at 100/100 both land on 100 and are
+     * not equally strong — that blade is 30 g against the layer's 13 g. So it
+     * answers "how good is this part for its generation", which is the right
+     * basis for a balanced roster and the wrong basis for claiming physical
+     * equivalence. `weightG` carries the latter, in grams, unnormalised.
+     *
+     * `ratings` stays raw beside it: a normalised value can be recomputed from
+     * the raw pair, a discarded raw value cannot.
+     *
+     * 🛑 FOR COMPARING OPPONENTS, NEVER FOR SUGGESTING A BUILD. A bey can only
+     * be ASSEMBLED within one generation — a Burst layer does not fit a Beyblade
+     * X ratchet — while battles are cross-generation. So this field belongs in a
+     * matchup, a leaderboard or a side-by-side, and a "build your own" picker
+     * must constrain to a single system's stack regardless of what it says.
+     */
+    ratingsNormalised?: PartRatings;
+    /** WBO format legality across 11 formats; an unstated format is absent. */
+    wboLegality?: PartWboLegality;
+    /**
+     * Other names for this exact part — the community abbreviation (`Armor Tip
+     * - Adventure` is `Ad`) and the other vendor's name. On 1,072 of 2,490 rows.
+     * Feeds search, so a buyer can find a part by the code printed on it.
+     */
+    aka?: string[];
+    /**
+     * Hasbro's own product code, a SEPARATE field from `productCodes`. On 309
+     * rows, and it is the Hasbro <-> Takara-Tomy equivalence stated outright.
+     */
+    hasbroCode?: string;
+    /** Attack / Defense / Stamina / Balance, per part. 793 rows. */
+    partType?: string;
+    /** Right-Spin / Left-Spin / Dual. 756 rows. */
+    spinDirection?: string;
+    /** Beyblade X's attribute label — "Sky" and siblings. 29 rows. */
+    element?: string;
+    /**
+     * The character this part belongs to in the story — `Bit Chip - Black
+     * Dranzer` is Kai Hiwatari's. Only 27 rows, but it is the sole place a PART
+     * is tied to a character.
+     */
+    owner?: string;
+    /** The episode this part appeared in. 22 rows. */
+    appearAnime?: string;
+    /**
+     * OUR OWN classification — what the part DOES, across generations.
+     *
+     * 🛑 `slot` cannot carry this. It mirrors the source's `Classification=`
+     * spelling and it is half of every document id (`${slot}--${code}`), and
+     * those ids are LIVE URLS (`/parts/{classification}/{code}`). Renaming a
+     * slot re-keys 2,490 rows and breaks every inbound link — a slug is the one
+     * field that cannot be quietly corrected later. So this is additive.
+     *
+     * It collapses the source's line-specific names onto one role:
+     * `bu-blade` / `qs-blade` / `blade` are all `blade`; the six Burst chip
+     * variants are all `chip`. Derived in `scripts/lib/part-slot-vocab.mjs`,
+     * which covers all 59 slots with 10 roles.
+     */
+    role?: PartRole;
+    /**
+     * Every stack role one moulding fills, listed TOP-TO-BOTTOM. A part that
+     * covers a single position does not carry this field at all.
+     *
+     * Integration is real and spans generations: HMS merges spin gear and blade
+     * base into a Running Core, a 4D Bottom (`D:D`, `X:D`) is a spin track and
+     * a performance tip in one piece, a Burst `disc-integrated-driver` is a disc
+     * and a driver, and `fusion-wheel--variares` is an energy ring and a fusion
+     * wheel. A Plastic-era base can integrate its Sub Attack Ring.
+     *
+     * 🛑 Load-bearing for any stack validation. `role` files an integrated part
+     * under its PRIMARY function, so a validator reading only that believes the
+     * other position is still empty and offers a part that cannot physically go
+     * there — it will refuse a legal build, and an exploded 3D view will show a
+     * gap where a solid piece is.
+     *
+     * 🛑 PER PART, NOT PER SLOT — that is the whole reason this is a field and
+     * not a lookup. `fusion-wheel--variares` integrates the ring and
+     * `fusion-wheel--jade` does not; same slot, different moulding. Jade is
+     * multi-PIECE, which is a different fact (see `pieceCount` when it lands).
+     *
+     * 🛑 Do NOT re-spell this as "fused". "Fusion Wheel" is a literal MFB slot
+     * name, so `fusedRoles` reads as *the roles of the fusion wheel* — the
+     * opposite of the meaning. The source's own slot names already use the
+     * right word: `disc-integrated-driver`, `ratchet-integrated-bit`.
+     *
+     * Populated by `scripts/derive-part-integration.mjs`, which reads it off the
+     * compositions each part actually appears in — the source states a 4D
+     * Bottom's `Classification` as plain "Performance Tip", so this cannot be
+     * copied from an infobox and is not guessed either.
+     */
+    integratedRoles?: PartRole[];
+    /**
+     * An owner-uploaded 3D model. Empty by default and deliberately so — the
+     * models are supplied by the owner, not ingested from anywhere.
+     *
+     * 🛑 NEVER served through `/api/media/[...slug]`. That route applies NO
+     * authentication, raw-pipes non-images with a 30-day immutable cache, and
+     * sits over a bucket whose storage rule is `allow read: if true` — so a GLB
+     * there is a public download. A mesh is the asset someone could build a
+     * competing game from, so it needs a signed, short-lived URL and an
+     * authenticated route of its own.
+     *
+     * 🛑 And a browser viewer cannot make a mesh unextractable — WebGL buffers
+     * can be dumped from any page that renders them. The honest mitigation is to
+     * publish a DECIMATED preview and keep the full-resolution mesh server-side;
+     * "protected" here means inconvenient, never impossible.
+     */
+    model3d?: {
+        url: string;
+        format: "glb";
+        sizeBytes: number;
+        /** A low-poly public preview, when the full mesh is held back. */
+        previewUrl?: string;
+        credit?: string;
+        creditUrl?: string;
+    };
+    /**
+     * An owner-uploaded sound, with its waveform for display.
+     *
+     * Renders through the existing `<MediaAudio>` primitive, so this needs no
+     * new UI primitive. `waveform` is a coarse amplitude array for drawing the
+     * trace without decoding the audio client-side.
+     */
+    sound?: {
+        url: string;
+        durationMs?: number;
+        waveform?: number[];
+        label?: string;
+    };
+    /**
+     * The Japanese name, the romanisation, and the kanji where the source gives
+     * one.
+     *
+     * 🛑 Top-level fields AS WELL AS `specs[]` rows, which is not duplication for
+     * its own sake: a `<title>`, an `og:title`, an hreflang alternate and a
+     * JSON-LD `alternateName` all need a FIELD. None of them can scan an array
+     * of label/value pairs for one whose label happens to read "Japanese name",
+     * and that is where these 1,068 values previously lived and died.
+     */
+    jpName?: string;
+    romaji?: string;
+    kanjiName?: string;
     /** `/media/<slug>`. 🛑 Never a raw Storage host URL. */
     image?: string;
     /** The wiki page the photo came from — the CC-BY-SA attribution target. */