@mohasinac/appkit 4.57.0 → 4.58.0

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;
+}

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

@@ -29,6 +29,7 @@
  * `Record<Generation, Slot[]>` would be the hand-written enumeration of Root
  * Cause #61 with a merge case it structurally cannot hold.
  */
+import type { AdminEditableRecord } from "./admin-edit";
 import type { BaseDocument } from "../../../_internal/shared/types/base-document";
 export declare const PART_GLOSSARY_COLLECTION: "partGlossary";
 export declare const MODEL_COMPOSITION_COLLECTION: "modelComposition";
@@ -271,7 +272,7 @@ export interface PartWboLegality {
  * 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 {
+export interface PartGlossaryDocument extends BaseDocument, AdminEditableRecord {
     /** `${slot}--${codeOrSlug}` — both halves, because a code is not unique. */
     id: string;
     /** Buyer-facing label: "Performance Tip", "Fusion Wheel". */

package/dist/features/pre-orders/components/MarketplacePreorderCard.js

@@ -19,6 +19,7 @@ import { normalizeRichTextHtml } from "../../../utils/string.formatter.js";
 import { PreorderBadge } from "./PreorderCard.js";
 import { WishlistHeartButton } from "../../wishlist/components/WishlistHeartButton.js";
 import { CardStoreLine } from "../../products/components/CardStoreLine.js";
+import { ProductOwnerQuickActions } from "../../products/components/ProductOwnerQuickActions.js";
 const DEFAULT_LABELS = {
     preOrderBadge: "Pre-order",
     featuredBadge: "Featured",
@@ -69,11 +70,23 @@ export function MarketplacePreorderCard({ product, className = "", variant = "gr
                 _jsxs(_Fragment, { children: [_jsxs(Row, { className: "min-w-0", align: "start", justify: "between", gap: "sm", children: [_jsx(TextLink, { href: detailHref, className: "min-w-0 flex-1", children: _jsx(Text, { size: "sm", weight: "medium", color: "primary", truncate: 2, children: product.title }) }), wishlistActions && (_jsx(WishlistHeartButton, { size: "inline", inWishlist: inWishlist, addLabel: mergedLabels.addToWishlist, removeLabel: mergedLabels.removeFromWishlist, onToggle: handleWishlist }))] }), _jsx(CardStoreLine, { storeName: product.storeName, storeId: product.storeId }), _jsxs(Row, { align: "center", gap: "sm", wrap: true, children: [_jsx(Text, { className: "text-primary", size: "sm", weight: "bold", children: _jsx(GatedPrice, { children: formatCurrency(product.price, getDefaultCurrency()) }) }), shipDate && _jsx(PreorderBadge, { shipDate: shipDate })] }), _jsx(Button, { type: "button", variant: "primary", size: "sm", textSize: "xs", className: "self-start mt-0.5", onClick: handleNavigate, children: mergedLabels.reserveNow })] })) : (
                 /* ── Full grid layout ── */
                 _jsxs(_Fragment, { children: [_jsx(TextLink, { href: detailHref, children: _jsx(Text, { size: "sm", weight: "medium", color: "primary", truncate: 2, children: product.title }) }), _jsx(CardStoreLine, { storeName: product.storeName, storeId: product.storeId }), product.description ? (_jsx(RichText, { html: normalizeRichTextHtml(product.description), proseClass: "prose prose-sm max-w-none dark:prose-invert prose-p:my-0", className: "line-clamp-2 text-[length:var(--appkit-text-xs)] text-[var(--appkit-color-text-muted)]" })) : null, _jsxs(Row, { justify: "between", className: "mt-1", gap: "sm", children: [_jsx(Text, { size: "sm", weight: "semibold", color: "primary", children: _jsx(GatedPrice, { children: formatCurrency(product.price, getDefaultCurrency()) }) }), shipDate && _jsx(PreorderBadge, { shipDate: shipDate })] }), _jsxs(Row, { justify: "between", className: "mt-auto pt-[var(--appkit-space-2)]", gap: "sm", children: [_jsx(Button, { type: "button", variant: "primary", size: "sm", textSize: "xs", className: "flex-1", onClick: handleNavigate, children: mergedLabels.reserveNow }), onAddToCart ? (_jsx(Button, { type: "button", variant: "outline", size: "sm", textSize: "xs", className: "flex-1", onClick: (e) => { e.stopPropagation(); onAddToCart(product); }, children: mergedLabels.addToCart })) : null, wishlistActions ? (_jsx(WishlistHeartButton, { size: "inline", inWishlist: inWishlist, addLabel: mergedLabels.addToWishlist, removeLabel: mergedLabels.removeFromWishlist, onToggle: handleWishlist })) : null] })] })) })] }));
-    if (!renderOwnerActions)
+    /*
+     * 🛑 Default, not opt-in. Nothing in either repo ever passed
+     * `renderOwnerActions`, so this toolbar was unreachable on every grid that
+     * mounts this card (Root Cause #8 — a slot shell rendered with zero render
+     * props). A card is resource-specific by construction, so it names its own
+     * resource rather than being threaded one; the prop stays as an override.
+     */
+    const ownerActions = renderOwnerActions
+        ? renderOwnerActions()
+        : product.id
+            ? (_jsx(ProductOwnerQuickActions, { productId: String(product.id), storeId: product.storeId ? String(product.storeId) : undefined, recordLabel: product.title, placement: "card" }))
+            : null;
+    if (!ownerActions)
         return card;
     /*
      * Sibling of the card, never a child — see the prop's docstring. `z-20`
      * clears this card's own overlays, which all sit at `z-10`.
      */
-    return (_jsxs(Div, { className: "relative h-full", children: [card, _jsx(Div, { className: "absolute right-2 bottom-2 z-20", children: renderOwnerActions() })] }));
+    return (_jsxs(Div, { className: "relative h-full", children: [card, _jsx(Div, { className: "absolute right-2 bottom-2 z-20", children: ownerActions })] }));
 }

package/dist/features/products/components/MarketplaceBundleCard.js

@@ -14,6 +14,7 @@ import { BaseListingCard, Div, GatedPrice, PricesOnly, Row, Span, Stack, Text, T
 import { MediaImage } from "../../media/MediaImage.js";
 import { computeBundleDiscount } from "../../../_internal/shared/features/categories/bundle-pricing.js";
 import { BUNDLE_COPY } from "../../../_internal/shared/features/categories/bundle-copy.js";
+import { RecordOwnerQuickActions } from "../../admin/components/RecordOwnerQuickActions.js";
 const DEFAULT_LABELS = {
     bundleBadge: "Bundle",
     inStockBadge: "In stock",
@@ -58,11 +59,23 @@ export function MarketplaceBundleCard({ bundle, className = "", variant = "grid"
                                                     ? formatCurrency(price, getDefaultCurrency())
                                                     : "—" }), discount && (_jsx(Text, { size: "xs", color: "muted", className: "line-through", children: formatCurrency(discount.originalTotal, getDefaultCurrency()) }))] }) }) }), _jsx(Text, { className: "text-[var(--appkit-color-text-muted)]", size: "xs", children: mergedLabels.itemsLabel(memberCount) })] }), _jsx(Div, { className: CLS_VIEW_BTN, role: "button", tabIndex: 0, onClick: handleNavigate, onKeyDown: (e) => { if (e.key === "Enter" || e.key === " ")
                             handleNavigate(); }, children: "View Bundle" })] })] }));
-    if (!renderOwnerActions)
+    /*
+     * 🛑 Default, not opt-in. Nothing in either repo ever passed
+     * `renderOwnerActions`, so this toolbar was unreachable on every grid that
+     * mounts this card (Root Cause #8 — a slot shell rendered with zero render
+     * props). A card is resource-specific by construction, so it names its own
+     * resource rather than being threaded one; the prop stays as an override.
+     */
+    const ownerActions = renderOwnerActions
+        ? renderOwnerActions()
+        : bundle.id
+            ? (_jsx(RecordOwnerQuickActions, { resource: "BUNDLE", recordId: String(bundle.id), recordLabel: String(bundle.name), placement: "card" }))
+            : null;
+    if (!ownerActions)
         return card;
     /*
      * Sibling of the card, never a child — see the prop's docstring. `z-20`
      * clears this card's own overlays, which all sit at `z-10`.
      */
-    return (_jsxs(Div, { className: "relative h-full", children: [card, _jsx(Div, { className: "absolute right-2 top-2 z-20", children: renderOwnerActions() })] }));
+    return (_jsxs(Div, { className: "relative h-full", children: [card, _jsx(Div, { className: "absolute right-2 top-2 z-20", children: ownerActions })] }));
 }

package/dist/features/products/components/MarketplacePrizeDrawCard.js

@@ -11,6 +11,7 @@ const CLS_PRIZE_PILL = "inline-flex items-center rounded-full bg-fuchsia-600 px-
 import { BaseListingCard, Button, Div, GatedPrice, Row, Span, Stack, Text, TextLink } from "../../../ui/index.js";
 import { MediaImage } from "../../media/MediaImage.js";
 import { CardStoreLine } from "./CardStoreLine.js";
+import { ProductOwnerQuickActions } from "./ProductOwnerQuickActions.js";
 const DEFAULT_LABELS = {
     prizeDrawBadge: "Prize draw",
     pendingBadge: "Reveal pending",
@@ -100,11 +101,23 @@ export function MarketplacePrizeDrawCard({ product, className = "", variant = "g
                         }, className: selectable || isSelected
                             ? "opacity-100"
                             : "opacity-0 pointer-events-none group-hover:opacity-100 group-hover:pointer-events-auto transition-opacity" }))] }), _jsxs(BaseListingCard.Info, { variant: variant, children: [_jsx(TextLink, { href: String(detailHref), children: _jsx(Text, { size: "sm", weight: "medium", color: "primary", truncate: 2, children: product.title }) }), _jsx(CardStoreLine, { storeName: product.storeName, storeId: product.storeId }), _jsxs(Row, { justify: "between", className: "mt-1", gap: "sm", children: [_jsx(Text, { size: "sm", weight: "semibold", color: "primary", children: _jsxs(GatedPrice, { label: "Sign in to see the entry price", children: [formatCurrency(pricePerEntry, getDefaultCurrency()), " ", _jsx(Span, { size: "xs", weight: "normal", className: "text-[var(--appkit-color-text-muted)]", children: mergedLabels.pricePerEntryLabel })] }) }), max > 0 ? (_jsx(Text, { className: "text-[var(--appkit-color-text-muted)]", size: "xs", children: mergedLabels.entriesRemainingLabel(remaining, max) })) : null] }), countdown ? (_jsxs(Text, { className: "text-[var(--appkit-color-text-muted)]", size: "xs", children: [status === "pending" ? "Opens in" : "Closes in", " ", countdown] })) : null, _jsx(Button, { type: "button", variant: "primary", size: "sm", textSize: "xs", className: "mt-2 w-full", onClick: handleNavigate, disabled: status === "closed" || remaining === 0, children: mergedLabels.enterDraw })] })] }));
-    if (!renderOwnerActions)
+    /*
+     * 🛑 Default, not opt-in. Nothing in either repo ever passed
+     * `renderOwnerActions`, so this toolbar was unreachable on every grid that
+     * mounts this card (Root Cause #8 — a slot shell rendered with zero render
+     * props). A card is resource-specific by construction, so it names its own
+     * resource rather than being threaded one; the prop stays as an override.
+     */
+    const ownerActions = renderOwnerActions
+        ? renderOwnerActions()
+        : product.id
+            ? (_jsx(ProductOwnerQuickActions, { productId: String(product.id), storeId: product.storeId ? String(product.storeId) : undefined, recordLabel: product.title, placement: "card" }))
+            : null;
+    if (!ownerActions)
         return card;
     /*
      * Sibling of the card, never a child — see the prop's docstring. `z-20`
      * clears this card's own overlays, which all sit at `z-10`.
      */
-    return (_jsxs(Div, { className: "relative h-full", children: [card, _jsx(Div, { className: "absolute right-2 top-2 z-20", children: renderOwnerActions() })] }));
+    return (_jsxs(Div, { className: "relative h-full", children: [card, _jsx(Div, { className: "absolute right-2 top-2 z-20", children: ownerActions })] }));
 }

package/dist/features/products/components/ProductGrid.js

@@ -17,6 +17,7 @@ import { PRODUCT_FEATURE_CARD_MAX_VISIBLE } from "../constants/product-features.
 import { normalizeListingType } from "../utils/listing-type.js";
 import { pluginFor } from "../../../_internal/shared/listing-types/_registry.js";
 import { WishlistHeartButton } from "../../wishlist/components/WishlistHeartButton.js";
+import { ProductOwnerQuickActions } from "./ProductOwnerQuickActions.js";
 const __P = {
     p3: "p-[var(--appkit-space-3)]",
 };
@@ -125,7 +126,22 @@ export function ProductCard({ product, href, onClick, onAddToWishlist, isWishlis
                                             onAddToCart(product);
                                         }, className: "justify-center text-[length:var(--appkit-text-xs)]", children: [_jsx("svg", { className: "h-3.5 w-3.5 flex-shrink-0", fill: "none", stroke: "currentColor", strokeWidth: 2, viewBox: "0 0 24 24", "aria-hidden": "true", children: _jsx("path", { strokeLinecap: "round", strokeLinejoin: "round", d: "M3 3h2l.4 2M7 13h10l4-8H5.4m1.6 8L5 3H3m4 10v7a1 1 0 001 1h8a1 1 0 001-1v-7M9 21h6" }) }), "Cart"] }))] }))] })] })] }));
     const wrapped = href && !selectionMode ? (_jsx(Link, { href: href, className: "block h-full", children: cardBody })) : (cardBody);
-    if (!renderOwnerActions || selectionMode || isSelected)
+    /*
+     * 🛑 Default, not opt-in — nothing in either repo ever passed
+     * `renderOwnerActions`, so this toolbar was unreachable on every product
+     * grid in the app despite the prop, the docstring and the positioning all
+     * being present (Root Cause #8).
+     *
+     * `ProductOwnerQuickActions`, not the generic wrapper: a product is the one
+     * collection a SELLER can also own, so its endpoints live under
+     * `SELLER_ENDPOINTS` and its clone has a bespoke redirect to the copy's
+     * editor. `storeId` is the store SLUG, which is what `SessionUser.storeId`
+     * holds — the component renders nothing for anyone who owns neither.
+     */
+    const ownerActions = renderOwnerActions ? (renderOwnerActions()) : product.id ? (_jsx(ProductOwnerQuickActions, { productId: String(product.id), storeId: product.storeId ? String(product.storeId) : undefined, recordLabel: product.title, placement: "card" })) : null;
+    // Selection is still suppressed: a bulk-select gesture and a per-record edit
+    // are different intents, and offering both at once invites the wrong one.
+    if (!ownerActions || selectionMode || isSelected)
         return wrapped;
     /*
      * 🛑 OUTSIDE the anchor, as a sibling — never inside `cardBody`.
@@ -144,7 +160,7 @@ export function ProductCard({ product, href, onClick, onAddToWishlist, isWishlis
      *
      * `z-20` beats the in-card overlays, which all sit at `z-10`.
      */
-    return (_jsxs(Div, { className: "relative h-full", children: [wrapped, _jsx(Div, { className: "absolute right-2 top-14 z-20", children: renderOwnerActions() })] }));
+    return (_jsxs(Div, { className: "relative h-full", children: [wrapped, _jsx(Div, { className: "absolute right-2 top-14 z-20", children: ownerActions })] }));
 }
 function ProductListRow({ product, onClick, onAddToWishlist, isWishlisted, }) {
     const discount = product.originalPrice && product.originalPrice > product.price

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

@@ -379,6 +379,24 @@ export interface ProductDocument extends BaseDocument {
      * defects welded into the TITLE.
      */
     unitLabel?: string;
+    /**
+     * This listing is a complete BEY, and this is which one.
+     *
+     * The `beys` document id, which is also its slug and also the URL
+     * (`/beys/{beyId}`) with no re-derivation — the same property that made
+     * `partGlossaryId` a single id rather than a pair.
+     *
+     * 🛑 THE EXACT COUNTERPART OF `partGlossaryId`, and the pair is what makes
+     * the seller's "single" choice meaningful: a single item is either one named
+     * bey or one named part, and those are the only two things in the catalogue
+     * that have an identity to point at. A lot has neither, which is why it
+     * files under a non-leaf CATEGORY instead (see `isLot`).
+     *
+     * 🛑 Never set together with `partGlossaryId`. A listing is a whole bey or a
+     * component, not both — and the two link to different reference pages, so a
+     * row carrying both would render two contradictory "what is this" sections.
+     */
+    beyId?: string;
     /**
      * This listing is a COMPONENT, and this is which one.
      *

package/dist/features/seller/components/CategoryInlineSelect.d.ts

@@ -22,5 +22,14 @@ export interface CategoryInlineSelectProps {
      * `MAX_CATEGORY_ASSIGNMENTS`, which is what the repository refuses above.
      */
     maxAssignments?: number;
+    /**
+     * Scope the rows to LEAVES (a single item) or to COLLECTIONS (a lot).
+     *
+     * 🛑 `undefined` means UNSCOPED, which is what every existing call site
+     * gets — this cannot default, because a caller that does not know whether it
+     * is a lot must not be silently told it is a single. See `leafFilterFor`
+     * for why the server makes this load-bearing rather than cosmetic.
+     */
+    leavesOnly?: boolean;
 }
-export declare function CategoryInlineSelect({ value, onChange, placeholder, disabled, allowCreate, extraValues, onExtraValuesChange, maxAssignments, }: CategoryInlineSelectProps): React.JSX.Element;
+export declare function CategoryInlineSelect({ value, onChange, placeholder, disabled, allowCreate, extraValues, onExtraValuesChange, maxAssignments, leavesOnly, }: CategoryInlineSelectProps): React.JSX.Element;

package/dist/features/seller/components/CategoryInlineSelect.js

@@ -1,5 +1,6 @@
 "use client";
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import React from "react";
 import { PaginatedSelect } from "../../../ui/components/PaginatedSelect.js";
 import { CategoryQuickCreateForm } from "../../admin/components/CategoryQuickCreateForm.js";
 import { apiClient } from "../../../http/index.js";
@@ -7,14 +8,48 @@ import { ADMIN_ENDPOINTS, CATEGORY_ENDPOINTS } from "../../../constants/api-endp
 import { Stack } from "../../../ui/components/Layout.js";
 import { Text } from "../../../ui/components/Typography.js";
 import { MAX_CATEGORY_ASSIGNMENTS } from "../../products/repository/category-assignment.js";
+/**
+ * ── 🛑 LOT vs SINGLE SCOPES THE ROWS, AND THE SERVER ALREADY REFUSES THE
+ * WRONG ONE ───────────────────────────────────────────────────────────────
+ *
+ * `assertAssignmentShape` has enforced both directions since 2026-10-14
+ * (`ENFORCE_LEAF_FILING = true`):
+ *
+ *   a LOT at a LEAF     -> "A lot holds several different items, so it cannot
+ *                          be filed under X, which is a single-item category."
+ *   a SINGLE at a BRANCH -> "X has subcategories, so it describes a group
+ *                          rather than one item."
+ *
+ * Until now the picker offered EVERY category to both, so roughly half of all
+ * choices walked the seller into a 400 they could not act on. Scoping the rows
+ * is therefore not a convenience — it is the client half of a rule the server
+ * already holds.
+ *
+ * 🛑 `isLeaf` NEEDS NO ROUTE CHANGE. `/api/admin/categories` forwards its
+ * `filters` string straight into `categoriesRepository.list`, and the public
+ * `/api/categories` whitelists `isLeaf` in `SAFE_CATEGORY_FILTER_FIELDS`. So
+ * this is a query-string addition, not new endpoint surface — which is also
+ * why it can ship without a build to verify it.
+ *
+ * `undefined` means UNSCOPED, which is what every existing caller gets. A
+ * caller that does not know whether it is a lot must not be silently told it
+ * is a single.
+ */
+function leafFilterFor(leavesOnly) {
+    if (leavesOnly === undefined)
+        return null;
+    return leavesOnly ? "isLeaf==true" : "isLeaf==false";
+}
 // Admin: paginated + server-side search via /api/admin/categories (admin/mod only).
 // Response via successResponse({ data: items, total }) → apiClient unwraps to { data, total, ... }.
-async function loadAdminCategoryOptions(query, page) {
+async function loadAdminCategoryOptions(query, page, leavesOnly) {
+    const leafFilter = leafFilterFor(leavesOnly);
     const params = new URLSearchParams({
         q: query,
         page: String(page),
         pageSize: "20",
         flat: "true",
+        ...(leafFilter ? { filters: leafFilter } : {}),
     });
     const res = await apiClient.get(`${ADMIN_ENDPOINTS.CATEGORIES}?${params}`);
     const items = (res.data ?? []).map((c) => ({
@@ -26,8 +61,13 @@ async function loadAdminCategoryOptions(query, page) {
 }
 // Seller: fetch all flat categories from the public unauthenticated endpoint,
 // filter client-side by query. Public endpoint returns { success, data: CategoryItem[] }.
-async function loadPublicCategoryOptions(query, _page) {
-    const params = new URLSearchParams({ flat: "true", pageSize: "200" });
+async function loadPublicCategoryOptions(query, _page, leavesOnly) {
+    const leafFilter = leafFilterFor(leavesOnly);
+    const params = new URLSearchParams({
+        flat: "true",
+        pageSize: "200",
+        ...(leafFilter ? { filters: leafFilter } : {}),
+    });
     const res = await fetch(CATEGORY_ENDPOINTS.FILTERED(params.toString()), { credentials: "include" });
     const json = await res.json().catch(() => ({}));
     const all = (json.data ?? []).map((c) => ({
@@ -38,8 +78,16 @@ async function loadPublicCategoryOptions(query, _page) {
     const items = q ? all.filter((c) => c.label.toLowerCase().includes(q)) : all;
     return { items, hasMore: false, nextPage: 2 };
 }
-export function CategoryInlineSelect({ value, onChange, placeholder = "Search categories…", disabled, allowCreate = true, extraValues, onExtraValuesChange, maxAssignments = MAX_CATEGORY_ASSIGNMENTS, }) {
-    const loadOptions = allowCreate ? loadAdminCategoryOptions : loadPublicCategoryOptions;
+export function CategoryInlineSelect({ value, onChange, placeholder = "Search categories…", disabled, allowCreate = true, extraValues, onExtraValuesChange, maxAssignments = MAX_CATEGORY_ASSIGNMENTS, leavesOnly, }) {
+    /*
+     * 🛑 MEMOISED, because `PaginatedSelect` consumes `loadOptions` inside an
+     * effect keyed on query/page. A fresh function identity every render
+     * re-triggers that effect, and the existing loaders are module-scope
+     * functions precisely to avoid it — binding the scope here would reintroduce
+     * the loop if it were done inline.
+     */
+    const base = allowCreate ? loadAdminCategoryOptions : loadPublicCategoryOptions;
+    const loadOptions = React.useCallback((query, page) => base(query, page, leavesOnly), [base, leavesOnly]);
     const primary = (_jsx(PaginatedSelect, { value: value || null, onChange: (v) => onChange(v ?? ""), loadOptions: loadOptions, placeholder: placeholder, disabled: disabled, createLabel: "category", drawerTitle: "Create Category", renderCreateForm: allowCreate
             ? ({ onCreated, onCancel }) => (_jsx(CategoryQuickCreateForm, { onSaved: (id, name) => onCreated({ value: id, label: name }), onCancel: onCancel }))
             : undefined }));

package/dist/features/seller/components/SellerProductShell.d.ts

@@ -19,6 +19,28 @@ import type { ListingType } from "../../products/types/index";
 export type ProductListingMode = ListingType | "bundle";
 export interface SellerProductDraft {
     title?: string;
+    /**
+     * LOT or SINGLE — and this had a field and a server rule but no control.
+     *
+     * 🛑 `ProductDocument.isLot` has existed since G3a and
+     * `ProductRepository.deriveTaxonomy` ENFORCES it at line 488
+     * (`assertAssignmentShape(resolved, input.isLot === true, …)`): a lot must
+     * file under a non-leaf category, a single may file anywhere. The form never
+     * set it, so every listing reached that check as a single — and a seller
+     * with a mixed pile had no way to say otherwise.
+     *
+     * The reason the rule exists is a claim about the ITEMS, not about counting:
+     * filing "12 assorted Burst beys" under `category-dragoon-g` asserts all
+     * twelve are Dragoon G.
+     */
+    isLot?: boolean;
+    /** How many items the lot holds. Optional even when `isLot` — a seller who
+     * has not counted the pile yet must still be able to save a draft. */
+    lotSize?: number;
+    /** The named bey this single IS, when the seller picked one. */
+    beyId?: string;
+    /** The named PART this single is, when it is a component rather than a bey. */
+    partGlossaryId?: string;
     slug?: string;
     description?: string;
     category?: string;
@@ -170,6 +192,23 @@ export interface SellerProductShellProps {
     renderCategorySelector?: (props: {
         value: string;
         onChange: (v: string) => void;
+        /**
+         * Whether the listing is a LOT, so the selector can offer the right rows.
+         *
+         * 🛑 OPTIONAL, like `extraValues` beside it and for the same measured
+         * reason: `QuickProductForm` is a second consumer of this slot and making
+         * a new prop required broke it immediately last time (Root Cause #20, a
+         * public prop change without its consumers — which the comment below
+         * already warns about). A selector that ignores this keeps today's
+         * behaviour exactly.
+         *
+         * 🛑 The server has enforced the split since 2026-10-14
+         * (`ENFORCE_LEAF_FILING = true`): a lot at a leaf and a single at a branch
+         * are both refused. So a selector that offers the wrong rows is not a
+         * cosmetic issue — it walks the seller into a 400 they cannot act on,
+         * which is what every seller hit before this prop existed.
+         */
+        isLot?: boolean;
         /**
          * 🛑 OPTIONAL, and that is the whole point. `QuickProductForm` is a second
          * consumer of this slot and making these required broke it immediately —