@mohasinac/appkit 4.45.0 → 4.47.0

package/dist/_internal/server/features/parts/data.js

@@ -0,0 +1,170 @@
+/**
+ * D12 — reads for the public part surfaces.
+ *
+ * 🛑 Wrapped in `React.cache` where a page+`generateMetadata` pair shares the
+ * call, and the NARROWEST shared call is cached rather than the exported one:
+ * `React.cache` memoises per argument list, so two call sites passing
+ * different arguments get two entries and dedupe nothing.
+ */
+import { cache } from "react";
+import { PART_GLOSSARY_COLLECTION, MODEL_COMPOSITION_COLLECTION, partGlossaryId, } from "../../../../features/parts/schemas/firestore.js";
+import { getAdminDb } from "../../../../providers/db-firebase/index.js";
+import { serverLogger } from "../../../../monitoring/server-logger.js";
+import { normalizeError } from "../../../../errors/normalize.js";
+/** The bucket cap. 87 is the largest real classification, so this clears it. */
+export const PART_SLOT_PAGE_SIZE = 120;
+/** One part, by `(slot, code|name)` — the only key this collection has. */
+export const getPartByKey = cache(async (slot, codeOrName) => {
+    try {
+        const snap = await getAdminDb()
+            .collection(PART_GLOSSARY_COLLECTION)
+            .doc(partGlossaryId(slot, codeOrName))
+            .get();
+        return snap.exists ? { id: snap.id, ...snap.data() } : null;
+    }
+    catch (err) {
+        const e = normalizeError(err);
+        serverLogger.warn("getPartByKey failed", { slot, codeOrName, error: e.message });
+        return null;
+    }
+});
+/**
+ * The models that use a part, hydrated.
+ *
+ * 🛑 `getAll` over the ids the part ALREADY carries, not a query. `usedBy` is
+ * written by the generator, so this is one round trip for N ids with no index
+ * and no scan — and it is bounded by how many models actually use the part
+ * (measured max: 20).
+ */
+export const getModelsUsingPart = cache(async (partId) => {
+    try {
+        const db = getAdminDb();
+        const part = await db.collection(PART_GLOSSARY_COLLECTION).doc(partId).get();
+        const ids = (part.data()?.usedBy ?? []).slice(0, 24);
+        if (ids.length === 0)
+            return [];
+        const col = db.collection(MODEL_COMPOSITION_COLLECTION);
+        const snaps = await db.getAll(...ids.map((id) => col.doc(id)));
+        return snaps
+            .filter((s) => s.exists)
+            .map((s) => ({ id: s.id, ...s.data() }));
+    }
+    catch (err) {
+        const e = normalizeError(err);
+        serverLogger.warn("getModelsUsingPart failed", { partId, error: e.message });
+        return [];
+    }
+});
+/** One model's composition, by the corpus doc id. */
+export const getCompositionById = cache(async (id) => {
+    try {
+        const snap = await getAdminDb().collection(MODEL_COMPOSITION_COLLECTION).doc(id).get();
+        return snap.exists ? { id: snap.id, ...snap.data() } : null;
+    }
+    catch (err) {
+        const e = normalizeError(err);
+        serverLogger.warn("getCompositionById failed", { id, error: e.message });
+        return null;
+    }
+});
+/**
+ * Hydrate the glossary rows a composition's slots point at, so a model page can
+ * link each slot and show its weight.
+ *
+ * ONE `getAll` for every slot — a per-slot read would be five round trips on a
+ * page that already has its own.
+ */
+export const getPartsForComposition = cache(async (compositionId) => {
+    const out = new Map();
+    try {
+        const db = getAdminDb();
+        const comp = await getCompositionById(compositionId);
+        const ids = (comp?.slots ?? [])
+            .map((s) => s.partId)
+            .filter((id) => !!id);
+        if (ids.length === 0)
+            return out;
+        const col = db.collection(PART_GLOSSARY_COLLECTION);
+        const snaps = await db.getAll(...[...new Set(ids)].map((id) => col.doc(id)));
+        for (const s of snaps) {
+            if (s.exists)
+                out.set(s.id, { id: s.id, ...s.data() });
+        }
+    }
+    catch (err) {
+        const e = normalizeError(err);
+        serverLogger.warn("getPartsForComposition failed", { compositionId, error: e.message });
+    }
+    return out;
+});
+/**
+ * Compositions for a named-model CATEGORY.
+ *
+ * 🛑 ONE INDEXED EQUALITY on `categoryId`, joined at SEED-GENERATION time.
+ *
+ * The first version queried `searchTxt` on `modelComposition` — a field that
+ * collection does not have, so it would have matched NOTHING while looking
+ * like a working read. The two id spaces genuinely disagree
+ * (`gen1-plastic-dragoon-f` vs `category-dragoon-f`), so a join is required;
+ * doing it in the generator makes it deterministic, reviewable in the
+ * committed seed, and one equality here instead of a name query.
+ *
+ * Measured: **210 of 259** compositions join. The join is on the normalised
+ * name, and on the name with its parenthetical expansion removed — the corpus
+ * titles HMS beys `Aero Knight MS (Aero Knight Metal Sky)` where the category
+ * is "Aero Knight MS", and without that second form only 150 matched.
+ *
+ * 🛑 A non-match leaves `categoryId` unset and this returns `[]`, so the model
+ * page shows no composition. That is honest: a fuzzy match could attach
+ * ANOTHER bey's parts, and a wrong part list is worse than none. Reconciling
+ * the remaining 49 is E3's job.
+ */
+export const getCompositionsForCategory = cache(async (categoryId) => {
+    if (!categoryId)
+        return [];
+    try {
+        const snap = await getAdminDb()
+            .collection(MODEL_COMPOSITION_COLLECTION)
+            .where("categoryId", "==", categoryId)
+            .limit(8)
+            .get();
+        return snap.docs.map((d) => ({ id: d.id, ...d.data() }));
+    }
+    catch (err) {
+        const e = normalizeError(err);
+        serverLogger.warn("getCompositionsForCategory failed", { categoryId, error: e.message });
+        return [];
+    }
+});
+/**
+ * Every part in one classification, alphabetical.
+ *
+ * 🛑 ONE equality on `slot`, bounded. The biggest bucket is 87 rows (attack
+ * rings) and the smallest 4 (armour) — measured, not assumed — so a page size
+ * of 120 shows every one of them today without a pager, and `truncated` tells
+ * the view to stop claiming a total the moment that stops being true.
+ *
+ * Firestore needs no composite index for one equality plus an `orderBy` on
+ * the SAME field it is already keyed by document id within… except it does
+ * for `(slot ==, name asc)`. So the sort is applied IN MEMORY: 87 rows is
+ * nothing to sort, and a declared index that exists only to order a bucket
+ * this small is an index to deploy, wait on, and remember.
+ */
+export const listPartsBySlot = cache(async (slot) => {
+    try {
+        const snap = await getAdminDb()
+            .collection(PART_GLOSSARY_COLLECTION)
+            .where("slot", "==", slot)
+            .limit(PART_SLOT_PAGE_SIZE)
+            .get();
+        const parts = snap.docs
+            .map((d) => ({ id: d.id, ...d.data() }))
+            .sort((a, b) => (a.name ?? "").localeCompare(b.name ?? ""));
+        return { parts, truncated: snap.size >= PART_SLOT_PAGE_SIZE };
+    }
+    catch (err) {
+        const e = normalizeError(err);
+        serverLogger.warn("listPartsBySlot failed", { slot, error: e.message });
+        return { parts: [], truncated: false };
+    }
+});

package/dist/_internal/server/features/parts/og.d.ts

@@ -0,0 +1,34 @@
+/**
+ * D12 — OG cards for the part surfaces.
+ *
+ * ── 🛑 NO IMAGE FETCHES, DELIBERATELY ──────────────────────────────────────
+ *
+ * Every other OG renderer here pulls a cover image through `resolveOgImageUrl`.
+ * These do not, and that is the one design decision worth stating: the project
+ * was suspended for **Fast Origin Transfer at 5.25× its allowance** (52.52 GB
+ * against 10 GB), traced to render-time image proxying (Root Cause #104). A
+ * glossary of 753 parts across 20 classifications is 774 OG routes; one remote
+ * fetch each, on a crawler sweep, is exactly the amplification that was just
+ * removed. Type on a gradient costs one lambda and nothing else.
+ *
+ * It also costs nothing in usefulness: a part has no photograph in our data.
+ * The honest card is its name, what kind of part it is, its weight and how
+ * many models use it — all four of which are facts we hold.
+ *
+ * ── 🛑 NO MONEY ON THE CANVAS ──────────────────────────────────────────────
+ *
+ * All eight money-bearing OG renderers were stripped for this reason: an OG
+ * image is a public image URL with the amount burned into the pixels, so no
+ * sign-in gate reaches it and no paywall markup describes it. A part card
+ * carries no price and never should, even though its page lists listings.
+ */
+import type { ReactElement } from "react";
+import { type PartGlossaryDocument, type PartSlot } from "../../../../features/parts/schemas/firestore";
+/** One part's card. */
+export declare function renderPartOg(part: PartGlossaryDocument | null | undefined, usedByCount: number, opts: {
+    siteName: string;
+}): ReactElement;
+/** One classification's card. */
+export declare function renderPartClassificationOg(slot: PartSlot, count: number, opts: {
+    siteName: string;
+}): ReactElement;

package/dist/_internal/server/features/parts/og.js

@@ -0,0 +1,66 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { PART_SLOT_LABEL, } from "../../../../features/parts/schemas/firestore.js";
+const BG = "#0f172a";
+const GRADIENT = "linear-gradient(135deg, #0f172a 0%, #1e293b 100%)";
+const MUTED = "#94a3b8";
+const ACCENT = "#5eead4";
+function shell(eyebrow, title, detail, siteName) {
+    return (_jsxs("div", { style: {
+            display: "flex",
+            width: "100%",
+            height: "100%",
+            background: BG,
+            fontFamily: "sans-serif",
+            position: "relative",
+            overflow: "hidden",
+            alignItems: "center",
+            justifyContent: "center",
+        }, children: [_jsx("div", { style: { position: "absolute", inset: 0, background: GRADIENT } }), _jsxs("div", { style: {
+                    position: "relative",
+                    display: "flex",
+                    flexDirection: "column",
+                    alignItems: "center",
+                    gap: 24,
+                    padding: "60px",
+                    textAlign: "center",
+                }, children: [_jsx("div", { style: {
+                            fontSize: 20,
+                            color: ACCENT,
+                            fontWeight: 600,
+                            letterSpacing: 3,
+                            textTransform: "uppercase",
+                        }, children: eyebrow }), _jsx("div", { style: {
+                            fontSize: title.length > 34 ? 56 : 76,
+                            color: "#ffffff",
+                            fontWeight: 700,
+                            lineHeight: 1.1,
+                        }, children: title }), detail && _jsx("div", { style: { fontSize: 28, color: MUTED }, children: detail }), _jsx("div", { style: { fontSize: 20, color: MUTED, marginTop: 8 }, children: siteName })] })] }));
+}
+/** One part's card. */
+export function renderPartOg(part, usedByCount, opts) {
+    if (!part)
+        return shell("Parts", "Beyblade parts", "", opts.siteName);
+    const classification = PART_SLOT_LABEL[part.slot] ?? part.classification ?? part.slot;
+    /*
+     * Only the facts we have. 23 of 753 parts carry a code and 98 carry a
+     * weight, so each clause is conditional — a card reading "0 g" or an empty
+     * bracket would be a claim we cannot support.
+     */
+    const bits = [
+        part.code ? `Code ${part.code}` : null,
+        typeof part.weightG === "number" ? `${part.weightG} g` : null,
+        usedByCount > 0
+            ? `Used by ${usedByCount} ${usedByCount === 1 ? "model" : "models"}`
+            : null,
+    ].filter((b) => b !== null);
+    return shell(classification, part.name, bits.join("  ·  "), opts.siteName);
+}
+/** One classification's card. */
+export function renderPartClassificationOg(slot, count, opts) {
+    const label = PART_SLOT_LABEL[slot] ?? slot;
+    return shell("Parts database", label, 
+    // `count` comes from the same bounded read the page renders, so the number
+    // on the card is the number on the page. A separate count query would be a
+    // second source that could disagree.
+    count > 0 ? `${count} recorded` : "", opts.siteName);
+}

package/dist/_internal/server/features/search/search-everything.d.ts

@@ -0,0 +1,75 @@
+import type { FirestoreValue } from "../../../../schemas/types";
+/** One matched row, deliberately minimal. */
+export interface SearchHit {
+    id: string;
+    title: string;
+    /** Where clicking goes. Built by the caller's route map, never guessed. */
+    href: string;
+    /** A one-line qualifier — the category path, the store name, the FAQ category. */
+    detail?: string;
+}
+export interface SearchGroup {
+    /** Stable key — `products`, `categories`, … matching the route map. */
+    key: string;
+    label: string;
+    hits: SearchHit[];
+    /**
+     * 🛑 `true` when the bounded fetch SATURATED, so the group's count is a
+     * FLOOR and must render as "6+" rather than "6". Same honesty rule as
+     * `truncated` on the listing queries — a saturated fetch reporting an exact
+     * total is a confident wrong number.
+     */
+    truncated: boolean;
+    /** The listing page for this resource, pre-filtered by the same query. */
+    moreHref: string;
+}
+export interface SearchEverythingResult {
+    q: string;
+    /** Parsed terms — empty for a query that normalises away, e.g. "!!!". */
+    terms: string[];
+    groups: SearchGroup[];
+    totalHits: number;
+}
+export interface SearchSource {
+    key: string;
+    label: string;
+    /** The collection to scan. */
+    collection: string;
+    /** Fields to project — a search page needs a title and a link, not a document. */
+    select: readonly string[];
+    /** Build a hit from a projected document. */
+    toHit: (id: string, data: SearchDocData) => SearchHit | null;
+    /** The pre-filtered listing page. */
+    moreHref: (q: string) => string;
+    /** Extra equality narrowing, e.g. `status == published`. */
+    where?: ReadonlyArray<readonly [string, unknown]>;
+}
+/** A projected Firestore document's fields. */
+export type SearchDocData = Record<string, FirestoreValue>;
+/** A projected document — the only shape this module reads. */
+interface SearchDoc {
+    id: string;
+    data(): SearchDocData;
+}
+interface SearchQueryRef {
+    where(field: string, op: string, value: unknown): SearchQueryRef;
+    select(...fields: string[]): SearchQueryRef;
+    limit(n: number): SearchQueryRef;
+    get(): Promise<{
+        docs: SearchDoc[];
+    }>;
+}
+interface MinimalDb {
+    collection(name: string): SearchQueryRef;
+}
+/**
+ * Run every source in parallel and group the results.
+ *
+ * 🛑 A source that THROWS yields an empty group and is logged — it never takes
+ * the page down. But the group is still RETURNED with `truncated: false` and no
+ * hits, which is indistinguishable from "nothing matched"… so the failure is
+ * logged loudly, because that is the one thing this cannot show the visitor
+ * without inventing an error state for a page that mostly worked.
+ */
+export declare function searchEverything(db: MinimalDb, q: string, sources: readonly SearchSource[]): Promise<SearchEverythingResult>;
+export {};

package/dist/_internal/server/features/search/search-everything.js

@@ -0,0 +1,120 @@
+/**
+ * D2 Fix 4 — CROSS-RESOURCE search.
+ *
+ * 🛑 `/search` is a pure REDIRECT today: it maps each of 15
+ * `SearchResourceType` values to a browse route and `redirect()`s, `noindex`.
+ * So there is **no cross-resource search at all** — the dropdown picks which
+ * single listing page to send you to, and a buyer searching "dranzer" cannot
+ * see that we have a product, an auction, a blog post and an FAQ about it.
+ *
+ * ── WHY THIS IS AFFORDABLE ─────────────────────────────────────────────────
+ *
+ * N bounded parallel queries, which is exactly the shape section 4.4's availability
+ * fan-out already uses (five clauses, 250 docs worst case). Every public
+ * collection carries `searchTxt` at **100% coverage** — measured 2026-10-12:
+ * products 71/71, stores 4/4, categories 416/416, blogPosts 20/20, events
+ * 12/12, faqs 85/85 — so each group is one `array-contains` push-down on the
+ * longest term plus an in-memory AND-refine, the same mechanism every listing
+ * page uses.
+ *
+ * One `Promise.all`, so the whole page is ONE round trip's latency rather than
+ * six, and Rule #6's budget is about sequential round trips.
+ *
+ * ── 🛑 NO PRICES, AND THAT IS A DESIGN DECISION ────────────────────────────
+ *
+ * The result rows carry a title, a type and a URL — never an amount. Prices
+ * are hidden from signed-out visitors, and a cross-resource page is the one
+ * surface where gating every row would be most of the markup. Showing names
+ * and linking through is honest, needs no `<GatedPrice>` wrapper, and cannot
+ * leak: there is nothing to leak.
+ *
+ * ── 🛑 WHAT IT DOES NOT REUSE, AND WHY ─────────────────────────────────────
+ *
+ * NOT `SearchRepository`. That class builds `title_=${q}` — a case-sensitive
+ * STARTS-WITH on `title` alone — so "dranzer" would not find "Beyblade
+ * Original Dranzer S" and "flat" would find nothing at all. It is reachable
+ * only through `/api/search`, whose own hook (`useSearch`) has zero consumers
+ * outside barrel re-exports. Recorded rather than deleted here; see F1.
+ */
+import { planSearchTxt } from "../../../../utils/search-txt-query.js";
+import { parseSearchTxtQuery, SEARCH_TXT_FIELD } from "../../../../utils/search-txt.js";
+import { serverLogger } from "../../../../monitoring/server-logger.js";
+import { normalizeError } from "../../../../errors/normalize.js";
+/** Per group, so one slow or failing collection cannot dominate the page. */
+const PER_GROUP = 6;
+/** The bounded window each push-down reads before the in-memory refine. */
+const SCAN = 60;
+/**
+ * Run every source in parallel and group the results.
+ *
+ * 🛑 A source that THROWS yields an empty group and is logged — it never takes
+ * the page down. But the group is still RETURNED with `truncated: false` and no
+ * hits, which is indistinguishable from "nothing matched"… so the failure is
+ * logged loudly, because that is the one thing this cannot show the visitor
+ * without inventing an error state for a page that mostly worked.
+ */
+export async function searchEverything(db, q, sources) {
+    const plan = planSearchTxt(q);
+    const terms = parseSearchTxtQuery(q ?? "");
+    /*
+     * 🛑 A query that normalises to nothing returns NOTHING, never everything.
+     * `"!!!"` and `"—"` have no tokens, and emitting no clause would make the
+     * push-down match every document in every collection — which is exactly the
+     * bug A2 fixed on `/api/products`, where `"!!!"` returned the whole
+     * published catalogue AS SEARCH RESULTS.
+     */
+    if (!plan.head) {
+        return { q: q ?? "", terms, groups: [], totalHits: 0 };
+    }
+    const groups = await Promise.all(sources.map(async (src) => {
+        const base = {
+            key: src.key,
+            label: src.label,
+            hits: [],
+            truncated: false,
+            moreHref: src.moreHref(q),
+        };
+        try {
+            let ref = db.collection(src.collection);
+            for (const [field, value] of src.where ?? [])
+                ref = ref.where(field, "==", value);
+            const snap = await ref
+                .where(SEARCH_TXT_FIELD, "array-contains", plan.head)
+                .select(...src.select, SEARCH_TXT_FIELD)
+                .limit(SCAN)
+                .get();
+            // AND-refine the remaining terms in memory — one push-down per query is
+            // all Firestore gives, so the rest is a filter over a bounded window.
+            const matched = snap.docs.filter((d) => {
+                const txt = d.data()[SEARCH_TXT_FIELD] ?? [];
+                return plan.rest.every((t) => txt.includes(t));
+            });
+            const hits = matched
+                .map((d) => src.toHit(d.id, d.data()))
+                .filter((h) => h !== null);
+            return {
+                ...base,
+                hits: hits.slice(0, PER_GROUP),
+                // Saturated window OR more matches than we show — either way the
+                // count on screen is a floor.
+                truncated: snap.docs.length >= SCAN || hits.length > PER_GROUP,
+            };
+        }
+        catch (err) {
+            const e = normalizeError(err);
+            serverLogger.warn("searchEverything: a source failed and renders as empty", {
+                source: src.key,
+                collection: src.collection,
+                error: e.message,
+            });
+            return base;
+        }
+    }));
+    const withHits = groups.filter((g) => g.hits.length > 0);
+    return {
+        q: q ?? "",
+        terms,
+        groups: withHits,
+        totalHits: withHits.reduce((n, g) => n + g.hits.length, 0),
+    };
+}

package/dist/_internal/server/features/search/search-sources.d.ts

@@ -0,0 +1,17 @@
+/**
+ * D2 Fix 4 — which collections `/search` spans, and how each row becomes a hit.
+ *
+ * 🛑 SIX SOURCES, not fifteen. The redirect page maps 15 `SearchResourceType`
+ * values, but nine of them are LISTING TYPES inside `products` — auctions,
+ * pre-orders, prize-draws, classified, digital-codes, live, art, bundles. One
+ * `products` query covers all of them, and a per-type query would be nine
+ * fan-outs returning overlapping rows from one collection.
+ *
+ * 🛑 Every field here was read off the live documents, not assumed. `stores`
+ * uses `storeName` (not `name`), `faqs` uses `question` + `seo.slug`, and
+ * `categories` must be filtered to listing rows because brands and bundles
+ * share the collection — the same trap that made the `/products` category
+ * facet offer "Takara-Tomy" as a browsable category (A1 item 4).
+ */
+import type { SearchSource } from "./search-everything";
+export declare const SEARCH_SOURCES: readonly SearchSource[];

package/dist/_internal/server/features/search/search-sources.js

@@ -0,0 +1,138 @@
+const str = (v) => typeof v === "string" && v.trim() ? v.trim() : null;
+const withQ = (base, q) => q.trim() ? `${base}?q=${encodeURIComponent(q.trim())}` : base;
+export const SEARCH_SOURCES = [
+    {
+        key: "products",
+        label: "Listings",
+        collection: "products",
+        /*
+         * 🛑 `status == published` ONLY. Availability is a per-row predicate over
+         * nine listing types (section 4.4: "available" is negation-shaped and no query
+         * expresses it), so a sold-out row can appear here — and that is correct
+         * for a search page, which answers "do you have this" rather than "can I
+         * buy it right now". The listing page it links to applies the scope.
+         */
+        where: [["status", "published"]],
+        select: ["title", "slug", "listingType", "categoryNames", "brand"],
+        toHit: (id, d) => {
+            const title = str(d.title);
+            if (!title)
+                return null;
+            const names = Array.isArray(d.categoryNames) ? d.categoryNames : [];
+            // The chain is stored LEAF-FIRST, so [0] is the most specific label.
+            const detail = [str(d.brand), names[0]].filter(Boolean).join(" · ");
+            return {
+                id,
+                title,
+                href: `/products/${str(d.slug) ?? id}`,
+                ...(detail ? { detail } : {}),
+            };
+        },
+        moreHref: (q) => withQ("/products", q),
+    },
+    {
+        key: "categories",
+        label: "Categories",
+        collection: "categories",
+        select: ["name", "categoryType", "tier", "categoryNames"],
+        toHit: (id, d) => {
+            const name = str(d.name);
+            if (!name)
+                return null;
+            /*
+             * 🛑 BRANDS AND BUNDLES SHARE THIS COLLECTION, and a plain listing
+             * category OMITS `categoryType` entirely — so this cannot be a query
+             * clause and has to be an in-memory test. Exactly the situation that
+             * made the `/products` facet offer "Takara-Tomy" and "Burst Battlers
+             * Pack" as browsable categories (A1 item 4): 9 of its 11 options were
+             * not categories.
+             *
+             * Brands are their own group below, so they are excluded here rather
+             * than dropped.
+             */
+            const type = str(d.categoryType);
+            if (type && type !== "sublisting")
+                return null;
+            return { id, title: name, href: `/categories/${id}` };
+        },
+        moreHref: (q) => withQ("/categories", q),
+    },
+    {
+        key: "brands",
+        label: "Brands",
+        collection: "categories",
+        // The one source with a real discriminator value to filter on.
+        where: [["categoryType", "brand"]],
+        select: ["name", "brandCountry"],
+        toHit: (id, d) => {
+            const name = str(d.name);
+            if (!name)
+                return null;
+            const detail = str(d.brandCountry);
+            return { id, title: name, href: `/brands/${id}`, ...(detail ? { detail } : {}) };
+        },
+        moreHref: (q) => withQ("/brands", q),
+    },
+    {
+        key: "stores",
+        label: "Stores",
+        collection: "stores",
+        where: [["status", "active"]],
+        // 🛑 `storeName`, not `name` — read off the live documents.
+        select: ["storeName", "storeCategory"],
+        toHit: (id, d) => {
+            const name = str(d.storeName);
+            if (!name)
+                return null;
+            return { id, title: name, href: `/stores/${id}` };
+        },
+        moreHref: (q) => withQ("/stores", q),
+    },
+    {
+        key: "blog",
+        label: "Articles",
+        collection: "blogPosts",
+        where: [["status", "published"]],
+        select: ["title", "slug", "category"],
+        toHit: (id, d) => {
+            const title = str(d.title);
+            if (!title)
+                return null;
+            const detail = str(d.category);
+            return {
+                id,
+                title,
+                href: `/blog/${str(d.slug) ?? id}`,
+                ...(detail ? { detail } : {}),
+            };
+        },
+        moreHref: (q) => withQ("/blog", q),
+    },
+    {
+        key: "faqs",
+        label: "Help & FAQs",
+        collection: "faqs",
+        where: [["isActive", true]],
+        select: ["question", "category", "seo"],
+        toHit: (id, d) => {
+            const question = str(d.question);
+            if (!question)
+                return null;
+            const category = str(d.category);
+            /*
+             * 🛑 `/faqs/[category]`, never a question slug. The route matches on
+             * `CATEGORY_KEYS.includes(category)` and falls back to "all", so a slug
+             * silently lands the reader on the full index — and the documents DO
+             * carry a `seo.slug` of exactly that shape, which makes the wrong link
+             * the obvious one. Same trap the authenticity hero slide hit.
+             */
+            return {
+                id,
+                title: question,
+                href: category ? `/faqs/${category}` : "/faqs",
+                ...(category ? { detail: category.replace(/_/g, " ") } : {}),
+            };
+        },
+        moreHref: (q) => withQ("/faqs", q),
+    },
+];